Multiple docs on one site

[softshape]

Hi all,

I'm trying to build a documentation for 3 products; they all should have separated sidebars but common header, like Docs and API on Docusaurus website. Is there any example how to configure this? So far I see only examples with one docs folder.

[Josh-Cena]

Docusaurus uses two doc plugins, one with source folder docs, the other community. However, the reason you need multiple doc plugins is because you need different versioning cycles. If you don't version your docs or you version them the same, you can use multiple sidebars instead within one plugin. Our doc plugin also has two sidebars: a Guide and an API.

[softshape]

What should be done to make it work? I split docs to 3 folders - docs/doc1, docs/doc2, docs/doc3, and made sidebars.js like this -

module.exports = {
  doc1Sidebar: ['doc1'],
  doc2Sidebar: ['doc2'],
  doc3Sidebar: ['doc3']
};

But it won't build. Which changes should be made except sidebars.js ?

[Josh-Cena]

No, you need to wrap it in an array.

module.exports = {
  doc1Sidebar: [{type: 'autogenerated', dirName: 'doc1'}],
  doc2Sidebar: [{type: 'autogenerated', dirName: 'doc2'}],
  doc3Sidebar: [{type: 'autogenerated', dirName: 'doc3'}],
};

[softshape]

This works, thank you!

[slorber]

great 👍

@Josh-Cena we should have a better error message in this case:

Loading of version failed for version "current"
TypeError: item.items.flatMap is not a function

Looks like we have a missing case in our validation system.
Let me know if you want to fix it, or I'll do it

[Josh-Cena]

It's because of the refactor in #6596. We now do validation after the shorthand normalization, because the shorthands are extremely permissive of the sidebar structure, and it's hard to validate properly. In fact, this original sidebar will become valid in the next version, with the error message improved as well in #6602. I'll see what we can do to improve the error message further, but it's hard to describe what the user needs to do, considering there are so many things that can be done (an array and an object both work). What about just catching the error and re-throwing with a link to the documentation?

[slorber]

Hmmm I see

{type: 'autogenerated', dirName: 'doc1'} should probably not considered as a shorthand though

Maybe we should emit an error if the shorthand has type: "autogenerated" | "category" | "doc" | "link" ?

I think it's worth adding at least a test case for the case above and try to improve a bit the message

[slorber]

Note that if your 3 products have very large documentations, you might want to "split" your site in 3 subsites + a portal. (ie if you edit ios doc, it doesn't have to rebuild android doc too uselessly)

You'll find this discussion interesting #6086