Versioning with Multirepo and Monorepo

[sebdeckers]

🚀 Feature

Combine docs from several modules into a single site. Docs may exist in separate repos or a monorepo.

Have you read the Contributing Guidelines on issues?

👍🏻

Motivation

I maintain a project comprised of several modules, each in their own versioning and documented repository. Other projects may manage multiple modules as a monorepo.

Pitch

Users expect a single documentation website where they can learn about all modules.

I would like to declare each module's repo URL, git submodule, or local directory path. Docusaurus should process any content files from the external modules with proper versioning and translation support.

[kevinbarabash]

I would love to use Docusaurus but am in the same situation. Would there be any interest in a pull request to add this feature?

[JoelMarcey]

@kevinbarabash Would love a pull request if you are willing? 👍

[kevinbarabash]

Cool! I'm not sure when I'll be able to get to this, but hopefully before the end of the year. 🤞

We were looking at building a custom documentation tool because of this requirement as well as others. I'd rather augment an existing tool than build something from scratch though. 🙂

[vjpr]

I wonder if this could be achieved with a plugin in Docosaurus v2.

[slorber]

We have the goal to make the docs plugin less "global", which means you should be able to use it multiple time on the same D2 site.

This way you could have /module1Docs + /module2Docsurl prefix, and put the markdowns in a git submodules if you want (the source directory is configurable already).

For translations, it might be more complicated, need to think about this.

[vjpr]

I started building a simple plugin to pull in the readme.md and docs folder for each package in my monorepo.

Would you suggest waiting a bit until the docs plugin is made more global? It did look like it was going to be a bit tricky because the docs plugin is rather complex.

[slorber]

I have not started the work on the docs plugin, and yes it might be tricky.

I think in the meantime you could have a build script that would just take all md's from submodules and copy the files to a non-versioned /docs folder. Each git submodule could be a subfolder of the /docs folder.

You won't have much flexibility over the docs urls (ie a single /docs prefix) and doc ids, but that should be a good workaround in the meantime.

[slorber]

Hey there

Can you read this RFC and tell me if you think it could be suitable for your usecases?

https://github.com/facebook/docusaurus/issues/3285

[slorber]

Note, it's possible to use multiple times the doc plugin on the same site now, I think it could be useful if you want to aggregate multiple docs in a same. site with different versioning. For example, iOS SDK in v1, v2, v3, and Android SDK in v1, v1.1...

See https://github.com/facebook/docusaurus/issues/2528#issuecomment-674112728

[slorber]

I believe it's already possible to assemble multiple git repos into a single Docusaurus site (some of our users actually do that).

• You can assemble the final doc as a pre-build step and put the md files are the correct location
• You can have multiple docs plugins instances, each one targeting a different git submodule/repo with the path options

We may still have missing configuration options to make life easier in some use-cases: in this case please open an issue explaining a concrete problem you encountered while trying to use multiple repos with Docusaurus, and we'll see how to unlock your usecase.

Personal note: it may take time to build a site containing multiple versioned docs. Sharding your site into multiple smaller instances can be more scalable. You can share your site config and custom CSS across site instances so that they somehow look the same and the transition from one to another is not too noticeable.

[ksandhya9]

I believe it's already possible to assemble multiple git repos into a single Docusaurus site (some of our users actually do that).

• You can assemble the final doc as a pre-build step and put the md files are the correct location
• You can have multiple docs plugins instances, each one targeting a different git submodule/repo with the path options

We may still have missing configuration options to make life easier in some use-cases: in this case please open an issue explaining a concrete problem you encountered while trying to use multiple repos with Docusaurus, and we'll see how to unlock your usecase.

Personal note: it may take time to build a site containing multiple versioned docs. Sharding your site into multiple smaller instances can be more scalable. You can share your site config and custom CSS across site instances so that they somehow look the same and the transition from one to another is not too noticeable.

Hi @slorber

Could you please kindly share any example for multiple docs plugin if possible? You can have multiple docs plugins instances, each one targeting a different git submodule/repo with the path options

[slorber]

We document "multiple docs plugins" as here: https://docusaurus.io/docs/docs-multi-instance

Git and submodules are outside the scope of Docusaurus. Docusaurus works as long as the files exist on the filesystem at the correct place. How you bring them there is not Docusaurus.

[ksandhya9]

Thank you @slorber