What would the recommended plugin to use for consolidating multiple sites?

[ssbarnea]

One of my primary reasons for switching to mkdocs was to be able to build a consolidated site that gets content from ~10 different projects, building an unified documentation website. Still, I wanted to keep building the standalone sides, mainly because I wanted to keep using readthedocs pull-request building feature, which is amazing for testing changes affecting documentation.

By reading about how to achieve this I realised that mostly I needed a mono-repo solution, even if the code itself would not necessarily be on a single repository. I think that bringing code together is not the real issue here as I am aware of two alternatives that would clearly be suitable: gig submodules or just as cloning/updating scripts.

So I ended up trying to make an integration POC and I found two plugins which might have helped me:

• mkdocs-monorepo-plugin by backstage (spotify) with 250 stars
• mkdocs-multirepo-plugin by @jdoiro3 with 48 stars
• mkdocs-multirepo by @wilhelmer with 22 stars

So far I attempted to use only the first one because the other two did not look as having a blazing popularity.

Sadly, I realised that that the first is not working with an file inclusion plugin that I used in order to allow rendering the README.md files from repository root as their main readme file. I reported the issue a week ago on backstage but so far no replies, maybe I did not ask in the right place.

It seems to be a discrepancy between how inclusions are supposed to (not) work with mkdocs, as symlinking is discouraged in one place while in another one the inclusion plugins break.

Does anyone have a success story to share regarding combining multiple mkdocs sites into a single one?

Probably by now we all know that got github hosted projects, we must have a real physical README.md on the repository root, as we cannot replace it with a symlink as github will not recognize it.

Attempt to use pymdown-extensions.snippets

After finding a suggestion from mkdocs/mkdocs#1373 (comment) about using snippets extension, i tried it. It worked nice for building the child-repos, but when attempting to build the parent side, the rendered snippets went empty, probably for the same reason: the path being relative to the built mkdocs.yml fine and not the child one. Not sure how to address this either.

[jdoiro3]

@ssbarnea, I'm the creator and only maintainer of mkdocs-multirepo-plugin and implemented a solution at my previous company (Unum Group) for the DS team to store docs in multiple repos that would automatically get updated into a main site. We used cookiecutter to generate workflow files automatically in the imported repo that would trigger the main docs repo's workflow when changes occurred in the docs dir of the imported repo.

@dkary is still on the team I believe and could provide more details of the implementation and any drawbacks of this approach. @dkary, feel free to add anything here.