Is it possible to have docusaurus docs built from multiple repos?

[arturg-acoustic]

Hi guys, I would love to try docusaurus, but we want to keep a single docusaurus for multiple microservices and have docs file close to source (in each repo). How could I make it work with docusaurus?

The mkdocs equivalent would be something like: https://github.com/jdoiro3/mkdocs-multirepo-plugin

[slorber]

Docusaurus does not care about a repository or git, it only care about what's on the filesystem, and it's your responsibility to pull the files the way you want.

You can look at the docs multi-instance concept in our docs.

[arturg-acoustic]

Thank you for the answer, but I do not really understand how multi-instance would help me in this case. Could you explain?

[slorber]

You can have one docs instance per microservice to document.
Docusaurus doesn't care about Git: just make sure to have ./docs-microservice1 and ./docs-microservice2 on your filesystem and it should work.

Please explain to me exactly what you don't understand.

[muescha]

I'm new to Docusaurus and eager to understand its functioning.

I'm attempting to determine how to replicate a similar setup. My aim is to separate the Docusaurus system from the content, resulting in two distinct repositories.

For the system:

• Repository: /muescha/my-website
• This repository contains all the Docusaurus-related components.

For the content:

• Repository: /muescha/my-content
• The documents are located within the /docs subfolder of this repository.

What would be the optimal approach for integrating this setup?

[muescha]

Why this setup? Perhaps I prefer to experiment with and test various systems while keeping the content within a single source repository.

[slorber]

Docusaurus does not care about repositories, git or any versioning system, it only cares about the location of files on the file system.

However I'd recommend to keep the docs/blog/content folders inside the Docusaurus website, because those files are transpiled by MDX to real React components. Those "content React components" should be part of your site to be able to access the required packages, including /node_modules/react. If you want to keep the /docs folder outside of your site, make sure you hoist the node_modules folder by using monorepo features.

---

Now if you want to keep separate repos, but keep your setup simple, you can just assemble the appropriate FS structure at build time with a script.

git clone <url>/my-website.git
git clone <url>/my-content.git
copy -R my-content my-website/docs
cd my-website
yarn install && yarn build

As far as I remember, some users have been using symlinks instead of copying the files around (more here: #3272).

[muescha]

maybe git submodule is an option?

[slorber]

@muescha Docusaurus doesn't care at all about what you are using to create the file system structure. You can use Git, Git Submodules, Mercurial, Subversion, ClearCase, FTP, Dropbox, Google Drive... Docusaurus will behave the same as long as the FS structure it sees is the same.

So, you are free to use Git Submodules if you want to, it's your part of the job to figure out a setup that works well with Docusaurus.