recommendations when running multiple Docusaurus sites for related projects

[DanRoscigno]

I am looking for input on having multiple Docusaurus sites, one for each project. Is one of these options better?

• docs.foo.com/project1
• docs.foo.com/project2
• docs.foo.com/project3

Or:

• project1.foo.com/docs
• project2.foo.com/docs
• project3.foo.com/docs

Requirements

• manage them separately (I do not want to build all three projects in a single job)
• separate 404 pages
• separate Algolia indices

What about Google indexing? The three products are related, will Google results be better if I used three subdomains?:

• project1.foo.com/docs
• project2.foo.com/docs
• project3.foo.com/docs

Thanks for your advice!

[slorber]

I am looking for input on having multiple Docusaurus sites, one for each project. Is one of these options better?

• docs.foo.com/project1
• docs.foo.com/project2
• docs.foo.com/project3

Or:

• project1.foo.com/docs
• project2.foo.com/docs
• project3.foo.com/docs

There's no better option IMHO, only options that fit better to your organization needs and available tools.

This is a bit related to the i18n deployment strategies we mention here: https://docusaurus.io/docs/i18n/tutorial#deploy-your-site

docusaurus.io/fr vs fr.docusaurus.io

• manage them separately (I do not want to build all three projects in a single job)
• separate 404 pages
• separate Algolia indices

Then it's better to have multiple Docusaurus sites instead of a single one with multi-docs plugin instances

Note: it's possible to share the infrastructure for all sites in a single Git repo. For example you could even use the same website folder, and use different config files pointing to different docs folders:

• yarn build --config docusaurus.config.project1.js
• yarn build --config docusaurus.config.project2.js

Or

• DOCS=project1 yarn build
• DOCS=project2 yarn build

Or you can create shared infrastructure packages and use these common packages across multiple sites.

What about Google indexing? The three products are related, will Google results be better if I used three subdomains?:

• project1.foo.com/docs
• project2.foo.com/docs
• project3.foo.com/docs

I'm not an expert on this matter, but I believe each subdomain has its own domain ranking, and having everything on a root/naked domain may give a better domain authority.

The strategy I would use is probably this:

• Deploy each project on standalone CDN deployments: project1.example.com
• Use CDN features to rewrite/proxy requests from example.com/project1 to project1.example.com
• Serve everything from your example.com root domain

This way, you have a higher root domain ranking and yet benefit from the ability to redeploy each project independently.

[ilg-ul]

it's better to have multiple Docusaurus sites instead of a single one with multi-docs plugin instances

I concur.

I had a single Jekyll site for multiple projects, but when I migrated to Docusaurus I split it, so now each project has a website folder and the documentation stays closer to the source code. (you can see the result here).

To keep things consistent, I created a template project, and a script invoked in each project to update the common files.

[DanRoscigno]

Thanks folks, I appreciate the help. Here is what we will end up doing:

• Keep the Markdown with the project code as recommended
• Have multiple separate Docusaurus builds writing to individual S3 buckets all served by one Cloudfront server
• https://docs.example.com/<productname>/ for each product
• For now, a single 404 page that has links for each product set.
• A single Algolia crawler with four actions blocks, one for each product name (keyed on the the product name with an index per product)

I will work on the 404 page later, I would guess that I can write some Javascript to return different content based on the requested URL.

[slorber]

👍

Note that you can easily have multiple 404 pages, similar to how we handle things for i18n (which is technically a separate Docusaurus site for each locale). You can catch all subrequests that do not match any resource and rewrite the to the build/404.html file of each deployment. For our site on Netlify, we have this setting:

# See https://docs.netlify.com/routing/redirects/redirect-options/#custom-404-page-handling
/fr/*             /fr/404             404
/pt-BR/*          /pt-BR/404          404
/ko/*             /ko/404             404
/zh-CN/*          /zh-CN/404          404

Regarding the Algolia crawler, one subtlety to handle is that when navigating within a site, you need to use the soft/SPA navigation (history.pushState()) while when navigating from one site to another site's search result, you need to use real browser navigation (history.location.href). Our theme exposes an externalUrlRegex to help you do that, or you can swizzle theme components if you need something more flexible.