Monorepo Feature Question

[jorgegomezcq]

Hi,

How does the experimental built-in projects plugin compare to the mkdocs-monorepo-plugin being developed by Backstage?

https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site/#built-in-projects-plugin

Are the project feature scopes/applications the same?

[squidfunk]

Great question. I wrote a lot about the goals of the plugin in #5800.

The projects plugin aims to offer a unified way of building multiple projects, which can be hosted in a single repository or in separate repositories. It will grow into being the swiss-army knife for building mono-repos, multiple languages, multiple versions, etc. It even already supports recursive use, so you can nest projects inside projects. Additionally, I'm currently working on building projects in topological order, so you can correctly link between, from, and to projects themselves.

Taking from the monorepo plugin's README, here's what we already support or plan to support:

• Support for multiple docs/ folders in Mkdocs
• Support for multiple navigations – not yet supported, but I already have a working prototype for this
• Support across multiple repositories – The plugin does not pull anything from git, but you could of course use submodules where you check out your projects, so this is supported via some third party logic by using git submodules.
• The same great Mkdocs developer experience

So, in the end the projects plugin will be a powerful tool that allows you to build complex multi-project setups. It tries to solve similar use cases as the following plugins, and sometimes borrows some ideas (not code):

• mkdocs-static-i18n
• mkdocs-monorepo-plugin
• mkdocs-multirepo-plugin

IIRC, the repo-management plugins have several shortcomings when it comes to navigation: they rely on statically defined navigation, i.e., you must explicitly list it in mkdocs.yml. The projects plugin will have none of those shortcomings, it will be able to merge the final navigation, altered by plugins, etc., which for example is essential for the blog plugin.

[squidfunk]

As of insiders-4.47.1, projects are guaranteed to be built in topological order.

[jorgegomezcq]

Hi, will the projects feature eventually make it out of the insiders program?

What is the release cycle for that?

Let me know if I should go read about this somewhere that I might have missed.

[kamilkrzyskow]

@jorgegomezcq The projects plugin will be available in the community version once the project reaches its funding goal: https://squidfunk.github.io/mkdocs-material/insiders/#24000-blockpaprika

[jorgegomezcq]

Thanks for clarifying how that is done for me. Much appreciated.

[jorgegomezcq]

Do you have any open source projects that you can recommend that are currently using the projects plugin to distribute documentation of several submodules/subprojects?

[jorgegomezcq]

Hmmm, I don't see the individual examples rendered in that demo page.

Should there be a table of contents somewhere that I can navigate to each example in the examples repository?

[alexvoss]

There is no table of contents at the moment and that is my fault. I have written code to compile one but started over-thinking it so it has not seen the light of day yet. I will try to finish a simpler version tomorrow. Hopefully it will appear on the GitHub Page for the examples repo in a day or two.

[jorgegomezcq]

Cool, thanks for working on that. I'm looking forward to seeing it when you finish it. Feel free to ping me here when it's deployed.

[jorgegomezcq]

@alexvoss Will the code to compile that TOC be publicly available since it is not directly more implementation code for the projects feature but configuration code?

[alexvoss]

It will be under MIT license like the rest of the examples, so you are free to reuse. Don't expect too much, though, since we decided to start out with the simplest possible implementation.