How to build docs site from multiple sources?

[borekb]

Say we want to have a site like this:

.
├── Guides/
│   ├── Getting Started
│   ├── Configuration
│   └── Advanced
├── Components reference/
│   ├── Component1.jsx
│   └── Component2.jsx
└── API reference/
    ├── /users
    └── /posts

It should be powered by Docusaurus overall but only the "Guides" section should be written manually in Markdown / MDX files, the two other "reference" sections should be generated automatically from our source codes (for example, by React Styleguidist for the "Components reference" section and by apiDoc for the "API reference" section; these are just examples and we're prepared to write custom code to e.g. generate custom MDX if Docusaurus requires that).

The ideal end state for us is:

• The left menu shows items like Component1.jsx and Components2.jsx dynamically, based on the external data. (Somewhat worryingly, I don't see the word "async" in https://v2.docusaurus.io/docs/docs-introduction/#sidebar.)
• Search indexes the entire site.
• "Everything can link to everything", e.g., the JSDoc in Component1.jsx can reference the "Getting started" guide somehow (we're fine doing some post/pre-processing).

Can Docusaurus v2 support that?

[slorber]

We have ability to configure the docs/page plugin paths, so you may be able to get that structure using 1 docs plugin + 2 pages plugin. Normally we should support using the same plugin multiple times (we plan to support that for docs soon).

The sidebar is a docs-only feature. We don't currently any sidebar of any kind on pages, where you start from a totally blank screen.

Currently, the way the sidebar is implemented in theme is tightly coupled to the docs plugin, so it won't be hard to reuse as it.

But I think it's something we should work on. It would be nice if the classic theme had some kind of decoupled component library (containing a reusable sidebar comp) that you would be able to use on your own custom pages.

Afaik it's not possible now (and is probably not a small refactor), but you can use the menu-xyz classes from Infima to create your own sidebar that would look like the docs one.

Opened an issue here: #3065

---

It's hard to say if Docusaurus is suitable for your need. The best is probably to make a POC and see what doesn't work.

[borekb]

Thanks. I think that it would be ideal if I could write plugin-content-ourreactcomponents and plugin-content-ourapi and those would somehow be able to contribute to the resulting sidebar. I'm not sure if component reuse is what I'm after, it's probably more like building the sidebar from various sources, by various plugins.

(My hypothetical plugins would basically be "docs" plugins, just parsing their content from things like .jsx source files or api.yaml. I hope that's somehow possible, at least in principle.)

[borekb]

It also looks to me that I could possibly fork the docusaurus-plugin-content-docs and just implement everything in there. The lifecycle methods look very powerful 👍.

[slorber]

Yes you can create or fork existing plugins if you have custom needs

The docs plugin is probably not the most easy to work with, and I'm doing some work to clean it and make it easier to deal with

[lugiger]

@slorber is it already possible to use the docs-content plugin multiple times or is this still being worked on?

[slorber]

Hi, this is not really related to the thread. Not possible yet but this is something I will work on soon.

[jrmyio]

Any updates on this?

[Josh-Cena]

@jrmyio Doc plugin multi-instance has been supported for quite a while. See https://docusaurus.io/docs/docs-multi-instance

[jrmyio]

@Josh-Cena ah thx for the quick response, I will check that out ;)!
Edit: Just confirmed this solves my use case. With this you essentially put general purpose docs in a separate package and then include them in a main project's docs. Pretty awesome!