Guidelines on how to use monorepo/submodules?

[leandrolerena]

I'm setting up MkDocs with the monorepo plugin. I got all up and running except for git-authors, where the Authors from the submodules are not displayed.

Are there any guidelines on how to use the plugin with submodules, or the monorepo in particular? If not, would you be open to add this feature? If yes, I'd also be open to contribute it.

[timvink]

Hi!

Yes, monorepo is not working because it copies files to a temp folder, meaning we lose information from git.

Happy to review a PR, but it might be a deep rabbit hole. #43 is a good place to start the trail. I think we might need to add support for symlinks, and check in the monorepo project that the new files are properly linked.

[leandrolerena]

Thanks for the reply!

Before digging into it, Material for MkDocs has a project plugin (which is currently only available for sponsors), see https://squidfunk.github.io/mkdocs-material/plugins/projects/

The project plugin will be available to the public by the sponsorware strategy and is compatible with Vanilla MkDocs as well. The monorepo plugin will probably be discontinued (see backstage/mkdocs-monorepo-plugin#106)

Would be interesting to test compatibility with that. Do you have any infos on it? I think that would be my first step before I dig into the code.

[timvink]

I have not looked into it. The sponsoring for mkdocs material would have to increase from 13k to 24k for it to become public though: https://squidfunk.github.io/mkdocs-material/insiders/#24000-blockpaprika

I do wish that happens very soon, but it's unlikely.

[squidfunk]

The project plugin will be available to the public by the sponsorware strategy and is compatible with Vanilla MkDocs as well. The monorepo plugin will probably be discontinued (see backstage/mkdocs-monorepo-plugin#106)

Would be interesting to test compatibility with that. Do you have any infos on it? I think that would be my first step before I dig into the code.

Author of Material for MkDocs here. The projects plugin does not make any assumptions about where your projects come from, so you could also put them into submodules and check them out before building it. Since the projects plugin will invoke local builds in the directory of where your submodules are located, this plugin should work without problems, as it does not use temporary directories.

If it doesn't, please raise an issue with a minimal reproduction and we're happy to investigate.

[leandrolerena]

Thanks to both of you for your inputs!

We will most probably switch fully to Material for MkDocs (thanks @squidfunk for the insight). I will report back here once I have evaluated the compatibility of the two. Feel free to close the issue @timvink and thanks again!

[leandrolerena]

Hello again,

I was able to test it with the projects plugin from @squidfunk.

WARNING - [project://.mkdocs-dummyproject] [git-authors-plugin] /home/user/projects/mkdocs/projects/mkdocs-dummyproject/docs/pages/page-1.md has not been committed yet. Lines are not counted

The mkdocs-dummyproject is registered as a submodule. When executing git status there, everything is committed.

nav:
  - Start: index.md
  - MkDocs Configuration: mkdocs.md
  - Test: project://mkdocs-dummyproject

A local build and serve with PWD in the submodule works perfectly.

[squidfunk]

Thanks for testing! This is likely related to the projects plugin, but we need a minimal reproduction to know for sure. If you can craft something that we can easily run on our machines, please create a complete bug report.

[leandrolerena]

Thanks for the input @squidfunk. I will create a complete bug report with reproducible example next week.

[leandrolerena]

Hi again @squidfunk

Here you go squidfunk/mkdocs-material#6970

Thanks a lot!