I don't have a strong opinion, and would be OK with "on request" invites :)

I agree with the concerns about openness. It does feel a bit weird to work in a private space, but this was the only way to gather a few interested authors and contributors. I'll note that this is also a common thing (private/internal space) to have when working as a team. I'm completely open to alternative setups!

Let me switch to this "on request" strategy: I've just sent an invite to @trell.

received.

All discussions were moved into the main, public repository 🙂

Of course, @squidfunk and I are in a position where we can reliably dedicate some of our time on MkDocs, and we completely understand that others might not be. Thanks a lot for offering your help!

Amazing, thanks a lot for joining! These are very nice ideas 🙂 I think other authors would be very interested chatting about this, like @Neoteroi 😄

Oh, I'm probably interested too! I wonder if mkdocstrings could be used for REST API / HTTP+JSON API docs 😄
Feel free to create discussions over there, I'll be happy to chat more 🙂

Great to have you!

That's awesome @bczsalba, thank you for joining! No worries about time constraints, we know FOSS is not the main occupation of many 🙂

So happy to get you on board @fralau!

Interesting idea, yes. It boils down to bringing a collaborative experience to a MkDocs site directly within the browser (user and group support, authentication, authorization, live editing and live previewing). Quite ambitious, love it! There were some previous efforts on this, happy to share more about this once you're in 😉

Hey @koaning, so cool that you're joining us! I'll send you an invite as soon as I'm in front of my laptop :)

Knuth is awesome =)

I do wonder if mkdocs is the right platform for this.. For technical writing I would consider first fastai's https://nbdev.fast.ai/, which is built on top of notebooks with Knuth in mind. For more elaborate writing,https://quarto.org/ is also really nice.

Perhaps mkdocs can learn some things from those approaches..

Some of this stuff can be achieved by integrating Obsidian.md as an editor for Markdown files. There are a few things that have to be considered since their Markdown flavor is a bit different that one used by MkDocs. Partly it's why I started to build my set of plugins called MkDocs Publisher. Basically it's a bridge that connects Obsidian and MkDocs that allows to publish Obsidian vault as a page with focus on simplicity for setup some publication aspects directly from Markdown files by frontmatter. It's more to talk about it and probably I should put it into the project documentation/web page.

Shameless plug with my own contribution to literate programming: markdown-exec (notably the Markdown example here) 😄

Yes, Jupyter and MkDocs are distinct, and at the same time they are like two alpinists attempting to escalate the same mountain from a different face. MkDocs is clearly more batch-oriented (since it aims at creating static sites); whereas Jupyter is more modular in its execution, supporting change of order and more interactivity.

Certainly, the common goal is to present together:

1. High-level concepts, expressed in natural language
2. Actual, formal code
3. The output of the code.

But I believe that each should remain itself and do well what they are doing, because each follows its own path.

When you are content to be simply yourself and don't compare or compete, everyone will respect you. (Lao Tze)

MkDocs has this elegantly simple idea that documentation (Markdown, with all its extensions) is code, part of the documentation can be computer code, and that part of this compiuter code can be executed (either at build time, or at viewing time in the browser).

@pawamoy The idea of using together Mkdocs-Macros and markdown-exec got me interested. 👀

It would be something worth experimenting, and see where it leads to.

Very nice plugins @mkusz! Ideas for small code improvements in the core to better serve plugin authors is exactly the kind of feedback and contributions we would love to get :)

Glad to have you here @lyz-code! The ability to use something else than the markdown Python package is a long standing feature request indeed. I myself would like to be able to experiment with other formats/tools like djot :) Happy to discuss more about this (even though it will not be a high priority, unless maybe if someone can commit to it!) 🚀

I didn't think anyone is looking for an exact amount of participation, only people that are interested in collaborating. I personally give only the time and effort I can. I support other things outside of this project, but there are times where I am able to contribute.

You're welcome! Regardless of how much time you can invest, it's probably a good thing to have you in the team, so you can at least follow the discussions that are of interest to you 🙂 I don't think we'd be able to invite a lot of authors if we were looking for specific levels of time commitment, as we know people are usually busy with lots of other things than FOSS 😅 So I'd say, join us and we'll see how things shape up. If everyone can commit even just a tiny amount of time, it's already much better than no time at all, I think.

Sounds good. Count me in then!

Thank you for joining @unverbuggt 🙂

Thanks @smarie! Invite sent, happy to chat about your plugins and MkDocs plugin system 🙂

@pawamoy Sure, yep. I was trying to say, "let's use @mkdocs/core better".

Specifically...

• @mkdocs/core currently has "maintain" permissions on mkdocs, so any users in that group can approve/merge PRs. Having a reasonably large number of individuals empowered to do that seems a good idea.
• We could/should probably have everyone who's invested above be on that team.
• If we do also want a semi-private team space(???), then we can have @mkdocs/core with "maintain" permissions on that space, rather than inviting contributors to the repo directly.

Make sense?

Yes, I meant a team that can be tagged.

I'm fine with open discussions, but I can see why we might want to do that in a separate space. Scikit-learn does that in a separate repo (https://github.com/scikit-learn/enhancement_proposals). I separate repo like mkdocs/enhancement_proposals could work well.

@timvink I agree, and I've suggested to make the repo public here: https://github.com/mkdocs/mkdocs-team-space/discussions/12.

@tomchristie

We could/should probably have everyone who's invested above be on that team.
@mkdocs/core currently has "maintain" permissions on mkdocs, so any users in that group can approve/merge PRs. Having a reasonably large number of individuals empowered to do that seems a good idea.

As much as I like reducing the bus factor and empowering people so that they maybe become maintainers, giving merge privilege this easily doesn't sound very sensible regarding security, especially after what we learned from the XZ event. For now, we still don't have a lot of maintainers that can reliably invest a decent amount of time in order to stay up-to-date with everything that happens in this repository. I myself do not feel confident I'm able to prevent malicious changes (or simply low-quality ones) from slipping into MkDocs, by reviewing all PRs and checking the ones that could have been merged without reviews. Some changes have consequences that are particularly hard to fully understand: we need extra, extra care when merging those. More merge access is also more attack surface for external attackers.

I fully trust some of the people who participated here, others have a online presence and reputation that is enough to vouch for them, but some others I don't know at all. Most of them have also said they don't have much time to spare on MkDocs. In short, I would prefer we don't apply the "on-request" strategy for giving merge privilege 🙂 Allowing them to approve PRs could be a good thing though, if it's not already possible.

EDIT: I'm however OK with having a second team, with less privileges than the core one. This would ease managing access/privileges for all these nice people 🙂

In short, I would prefer we don't apply the "on-request" strategy for giving merge privilege 🙂 Allowing them to approve PRs could be a good thing though, if it's not already possible.

I agree with @pawamoy here. I would suggest two levels for team members. New members should be able to review PRs and mark them (perhaps with tags) as 'ready to merge' or 'needs changes' or whatever is appropriate for that PR. Then the seasoned members with additional privileges can merge the 'ready to merge' PRs. This gives the team an opportunity to observe how new team members handle various situations and provide feedback so that they can grow and improve. In time, the new member can be given additional privileges if it is deemed appropriate.

I also had on my backlog for a long time the wish to build a standardized git 'meta plugin' that processes markdown pages just once and as fast as possible (multithreading, parallel, etc). Then plugins authors that use that information easily and efficiently. I even started an implementation on https://github.com/timvink/mkdocs-git-info-plugin but have never properly dedicated the time required.

I haven't completely forgotten that idea either @timvink! I remember that we talked about it in an issue in one of your git based plugin.

Thanks for your feedback 🙂 I'll see with other members of the org what alternative setup we could use instead of a private repository.

All discussions were moved into the main, public repository 🙂

Thanks for joining and helping @ojacques 😄

Thanks so much @wilhelmer! All the best to you too!

Amazing, I hope you get selected too :) I'll send you an invite asap!

Thanks for joining, and for your feedback @LukeCarrier 🙂
We're chatting right now, hopefully we'll have good news very soon 🙂

This is being addressed, and all the discussions that already happened in the private space will probably be moved into the public discussions of the mkdocs repository 🙂 I'll check with @tomchristie if we can do that tomorrow.

I feel that it might be good to explain something here ☺️

I'd love to put Material for MkDocs on more shoulders and I've started to build a team lately to pull that off that I financially compensate. The fact that Material for MkDocs is more or less managed by me for the last 8 years stems from its original purpose and its target group – it started as a theme built for non-web-devs, and that's still the main demographic. Most users have no front end skills, so can't really help out on anything in that domain, and the project has grown to be quite complex, so there're almost no low hanging fruits there. Frontend-savvy users use something like Docusaurus or Vitepress anyway, as they want more control, which is understandable. Additionally, they have a JS stack on their system anyway, which is an absolute no-go for many of our users, especially from within enterprises.

Another problem might be our use of a harder to learn paradigm called "Reactive Programming" (implemented in RxJS) to model the UI, as we cannot just use a predefined web framework like React or Svelte to strap on business logic on static HTML.

We have only lately begun to add plugins and business logic to the mix, and I expect more helping hands here in the near future as adoption grows. My goal is definitely to build a welcoming and inviting community, and I think we will eventually be successful with that. Making MkDocs more modular and inviting to third-party extension and plugin authors would definitely help.

All discussions were moved into the main, public repository 🙂

That's a good suggestion. However there weren't a lot of discussions. They would be the most recent ones in the General and Ideas categories, as well as all the ones in Maintenance and Meta. And since all discussions are in the same place now, there's nothing distinguishing them from previous ones.