Maintainership

[tomchristie]

Hey team,

I'm going to be stepping up as lead maintainer for MkDocs again. For those of you who don't know me, I'm the project's original author and have worked on a stack of open source projects over the last decade.

There's a fantastic core here, but we're really not capitalising on that at the moment.

Priorities that I can see for the project are...

• A clean sharp new default theme.
• Improving the documentation.
• Simplifying the core project.

There's a couple of challenges here...

One of the pressing issues is that without a proper funding approach we're not going to be able to provide dedicated time towards improving MkDocs. Martin and his team have been doing a fantastic job of that over at Material for MkDocs, and there's plenty of scope for this project to also be drawing in funding and supporting its future development.

I can also see some challenges around the existing plugin architecture. Having themes be tied into Python packaging is going to hold back the project from having a wide adoption outside of the Python bubble. It also makes it difficult to provide safe theming options, since we're guiding users towards installing and running Python code where in many cases there's HTML templating & styling alternatives that would be sufficient. Navigating how we improve this is decidedly non-obvious.

As regards team management I don't have any significant concerns, although we will need invested parties stepping up. I do think it's important for the ecosystem that MkDocs has a strong and independant leadership distinct from Material for MkDocs, while still drawing from their expertise & experiance. We've got plenty of smart capable people here, and I'm sure we'll be able to step up to the mark, together.

I'll take an open video call this Saturday, for anyone who'd like to discuss any of the above as well as an opportunity for us to have some face-to-face time.

Tagging y'all for now...

@Andre601 @athackst @bczsalba @blueswen @byrnereese @chrieke @daizutabi @d0ugal @EddyLuten @facelessuser @fralau @greenape @Guts @JakubAndrysek @koaning @LukeCarrier @lyz-code @mondeja @ofek @ojacques @pawamoy @six-two @smarie @squidfunk @timmeinerzhagen @timvink @unverbuggt @waylan @wilhelmer

(And yes, we should probably sort out a @mkdocs/community team.)

[Andre601]

I personally would take some responsability in the documentation, be it reviewing changes or proposing own ones through PRs.
Though, in regards to proposing changes would it be great to collect a list of what should be changed here, so that I and others know what we could tackle and solve here... This can/should be applied to any other area of the projects (Have a public collection of things that should be dealt with).

I cannot quite participate in the video call, unless just listening in and sending messages is possible, as I lack the hardware (microphone) to really participate...

[d0ugal]

Hey team,

I'm going to be stepping up as lead maintainer for MkDocs again.

Welcome back Tom! Its good to see things picking up here again and I know the project will be in good hands with you. Who knows, maybe I'll find some time for MkDocs again one day 😄

I'll take an open video call this Saturday, for anyone who'd like to discuss any of the above as well as an opportunity for us to have some face-to-face time.

This sounds like a nice idea. Unfortunately Saturdays are generally not good for me so I wont join but I'll be following from the sides.

[per1234]

drawing in funding

I recommend setting up GitHub Sponsors. I personally find it to be the most convenient way to contribute financially to open source software projects. I was using GitHub Sponsors as a way to support MkDocs prior to the recent change in maintainership and would be happy to continue to do so.

[Andre601]

The project did have GitHub Sponsors. More accurately, Oprypin's account was used here for collecting the donations and he distributed it across all members (and contributors afaik).

Tho, with him stepping down, he removed the FUNDING.md file containing the sponsors info.

[pawamoy]

That's incorrect: the $10,000 donation from Bloomberg was split between several contributors, yes (using the Open Collective platform), but sponsorships created on @oprypin's sponsors profile were his and only his 🙂 (no issue with that of course, just clarifying)

[Andre601]

I see, thanks for the correction.

[pawamoy]

As regards team management I don't have any significant concerns, although we will need invested parties stepping up. I do think it's important for the ecosystem that MkDocs has a strong and independant leadership distinct from Material for MkDocs, while still drawing from their expertise & experiance. We've got plenty of smart capable people here, and I'm sure we'll be able to step up to the mark, together.

Didn't notice on first read, but I find this part a bit confusing. Is it speaking about building a team, or leadership? IIUC you are the leadership now @tomchristie ( 🎉 ), so I'm not sure why we make a special case of Material for MkDocs regarding building a team. Don't we want them on the team 🤔? Or did you mean that leadership will be embodied by the whole team? Not sure to understand 😛

[tomchristie]

As regards team management I don't have any significant concerns [...]

I find this part a bit confusing [...]

I'm referring to this thread, and suggesting that we can probably move past that.

I'm not sure why we make a special case of Material for MkDocs

It's by far the most dominant part of the MkDocs ecosystem, so it's in a more complex position than other projects.
(Just needs a little more mindfulness around how the two projects relate to each other.)

[pawamoy]

I see, thanks for the clarification 👍

[pawamoy]

I should have started with that: welcome back Tom! Glad you're stepping up and investing time in MkDocs again to lead its maintenance and growth 🙂 It's good to have someone dedicated to it, especially when they're the original author 😄 Happy to hop on the saturday call to chat 🙂

[pawamoy]

@tomchristie I've pinned the discussion.

[tomchristie]

Okay, I'll take an open call tomorrow, Sat 27th at 7 AM UTC on https://meet.google.com/fes-iqes-fyr
Appreciate the weekend Europe morning might not be best time for all, but it's a starting point.
Perhaps we'll be able to schedule within more sensible weekday working hours for a future call.

Edit: Confusing myself with timezones.

[Andre601]

For those who want to know the time in their timezone is here a link that should convert it: https://dateful.com/convert/utc?t=07
Alternatively is here an event Link: https://dateful.com/eventlink/2173958097

[squidfunk]

Unfortunately, I'm not able to make it today, I'm sorry. I hope y'all have some nice and productive face-to-face time! Maybe, afterwards, you can share what was discussed with the community, to let us all know what you've decided upon ☺️

[pawamoy]

Thanks @tomchristie and @fralau 🙂

The few things I wrote down:

• easing creation of new themes: we already link to a basic theme that serves as an example, but it probably doesn't provide the "Python packaging" bit. Maybe we could offer a Copier template that does just that.
• for a better DX when creating plugins: provide clear guidance and API to handle errors (exceptions, we already have PluginError), handle warnings (deprecations, etc.), and log messages (this one is quite good already, but I very recently found myself needing to support a once parameter when logging, to prevent the same message from showing many times).

[fralau]

Thanks @pawamoy !

[pawamoy]

Oh, I thought about it during the call but forgot to mention it: I had this idea recently to create a mkdocstrings handler for Jinja templates. Just an idea, but I already track my progress here: mkdocstrings/mkdocstrings#661. Since MkDocs themes are avid users of Jinja, I figured this was worth mentioning as it will help them document their templates.

[tomchristie]

Thanks @fralau, @pawamoy. ☺️

That was a really valuable call, appreciated the time with you both.

@fralau I spent a bit of time looking through mkdocs-macros-plugin after the call. Really smart approach. Much easier for adding content than wrangling tree processors. 🤔💭

[fralau]

@tomchristie Thanks! Coming from you, that ackowledgement goes straight to my heart.

To me, enriching markup with macros was a rather obvious idea, because wikis used to have that mechanism to enrich pages (see dokuwiki or Confluence).

Initially I played around with the old M4 macro processor, but it was archaic and generally nightmarish. Then I discovered jinja2 (which is also used in MkDocs for HTML templating) and it thought... Jinja2 can be used to enrich Markdown text files with the same ease as it can be used with HTML!

As I played around with this, I discovered that a range of use cases for plugins (though not all of them), could be quickly solved with macros defined in a simple python module (the plugin offers git info out of the box). I also facilitated their installation by inventing pluglets. Pluglets are still rather niche, but who knows, they might take off 🙂 .

(As a matter of fact, Jinja2 can be used for any type of text file, including for generating config files: the sky is the limit.)