Docusaurus: V2: document docs plugin multi-instance

[NikitaIT]

📚 Documentation

Usecase

As a developer, I want to be able to create 2 pages of documentation.

Why am I writing this?

This is often necessary, and oftentimes developers don't find the right way to do it. One of the official examples from the examples page in the documentation:

• Works: https://buildtracker.dev/docs/guides/guides
• Not works: https://buildtracker.dev/docs/guides/

Expected result

The image shows the expected result - two pages with two sidebars.

• First page is Docs with url /docs and index-page on /docs/doc1 from dir docs.
• Second page is Resources with url /resources and index-page on /resources/doc2 from dir resources.

Solution

Warning: md-link from resources to docs should be relative like [doc1](../docs/doc1)

// sidebarsDocs.js
module.exports = {
  docs: {
    Installation: ["doc1"], // from path `docs/doc1`
  },
};
// sidebarsResources.js
module.exports = {
  resources: {
    Installation: ["doc2"], // from path `resources/doc2`
  },
};

Then need to create files from docusaurus.config.js folder:

docs/
- doc1.md
resources/
- doc2.md

Then need to connect two content-docs plugins (one from preset-classic) with different ids.

// docusaurus.config.js
  presets: [
    [
      "@docusaurus/preset-classic",
      {
        docs: {
          // id: "w1", for first plugin-content-docs with "docs/" path, do not set this if you want versioning to work
          homePageId: "doc1",
          sidebarPath: require.resolve("./sidebarsDocs.js"),
        },
      },
    ],
  ],
  plugins: [
    [
      "@docusaurus/plugin-content-docs",
      {
        id: "w2", // for first plugin-content-docs with "resources/" path
        homePageId: "doc2",
        path: "./resources", // Path to data on filesystem, relative to site dir.
        routeBasePath: "resources", // URL Route.
        include: ["**/*.md"],
        sidebarPath: require.resolve("./sidebarsResources.js"),
        disableVersioning: true, // if not set with vesions, throw: Identifier 'React' has already been declared
      },
    ],
  ],

And set routes to themeConfig.navbar.items.

// docusaurus.config.js: themeConfig.navbar.items
{
        to: "docs/",
        label: "Docs",
        position: "left",
},
{
        to: "resources/",
        activeBasePath: "resources",
        label: "Resources",
        position: "left",
}

Alternative expected result

• First page is Docs with url /docs and index-page on /docs/doc1 from dir docs.
• Second page is Resources with url /docs/resources and index-page on /docs/resources from dir docs/resources.

Solution

Warning: not tested with docs versions

// sidebars.js
module.exports = {
  docs: {
    Installation: ["doc1"],
  },
  resources: {
    Installation: ["resources"],
  },
};

Then need to create files from docusaurus.config.js folder:

docs/
- resources/
- - // other files for Resources page will be in this folder 
- resources.md // index-page for Resources page, the same name with a content folder at the same level
- doc1.md

Then need to connect two content-docs plugins (one from preset-classic) with different ids.

// docusaurus.config.js
  presets: [
    [
      "@docusaurus/preset-classic",
      {
        docs: {
          // "docs/" path
          homePageId: "doc1",
          sidebarPath: require.resolve("./sidebars.js"),
        },
      },
    ],
  ],

And set routes to themeConfig.navbar.items with activeBaseRegex.

// docusaurus.config.js: themeConfig.navbar.items
{
        to: "docs/",
        activeBaseRegex: "^(.*docs\\/(?!(resources\\/?)).*)", // ignore route "docs/resources/..."
        label: "Docs",
        position: "left",
},
{
        to: "docs/resources/",
        activeBasePath: "docs/resources",
        label: "Resources",
        position: "left",
},

[NikitaIT]

P.S. I think this configuration is not intuitive, so it can be seen as a suggestion for simplification.

[slorber]

Hey @NikitaIT

The docs multi-instance system is brand new, it wasn't working before alpha 61, and we can definitively improve the doc (I left it undocumented on purpose so that we can get a bit of feedbacks of early adopters before writing some doc.

Both options look valid to me, but it will also depend on how you see versioning working on your site, and what URLs you want. If you have 2 plugin instances, each can have different versionion schemes (ios/android sdks for example). Also each plugin instance has its own URL prefix.

One plugin instance means shared URL prefix + same versioning for both docs.

Also worth mentioning that you can use special navbar items to link to docs: https://v2.docusaurus.io/docs/theme-classic/#navbar-docs-version-dropdown

Also, if you use docs, it means you want to use doc navigation, a sidebar etc... If you don't need that, you can also simply created a markdown page (added recently): https://v2.docusaurus.io/docs/creating-pages/#add-a-markdown-page

If you want to write some doc, I'll be happy to accept a PR

[NikitaIT]

About 2 docs with versions

It seems setting id in the classic with versioning is unnecessary, and breaks the documentation. So I remove id: "w1" from the example. And if 2 docs with versions for first we should set disableVersioning: true, because by default the second plugin will reload the versions and throw Identifier 'React' has already been declared.

[slorber]

Sorry but I don't understand what you mean 😅 if you can send a PR to Docusaurus website that allows me to see the problem on the deploy preview that would be helpful.

[NikitaIT]

@slorber This is not very important, just when adding folders with versions, the second instance of the plugin docs parses them again(without disableVersioning). Because both plugins do it at the same time, this leads to an error. The error is expected, but I decided to write about it here, just in case.

[jacksongoode]

Thanks @NikitaIT for a great tutorial on getting multiple, separate and unique, documentation pages!

[tjperry07]

I tested out method 1 on a clean install, and it returns a 404 error when navigating to Resources.
See the code https://github.com/tjperry07/doc-testing

I did find a method that worked using multiple sidebars.

sidebars.js

module.exports = {
  docs: {
    Docusaurus: ['doc1'],
  },
  dataProd: {
    Welcome: ['dataProd/welcome_data']
  }
};

inside of /docs

.
├── dataProd
│   └── welcome_data.md
└── doc1.md

docusaurus.config.js

        {
          to: 'docs/',
          label: 'Docs',
          position: 'left',
        },
        {
          to: "docs/dataProd/welcome_data",
          label: "Data Prod",
          position: "left",
        },

[mathetos]

I was able to get three different "docs" sections added while running version 2.0.0-alpha-64.

They each have sub-directories, and custom sidebars. Worked really well once I finally figured it all out. Often, when I added new docs into new sub-directories, I had to restart yarn for the new files to be recognized. Other than that, if this was explicitly documented it would have saved me at least an hour of fidgeting and guessing.

plugins: [
    [
      "@docusaurus/plugin-content-docs",
      {
        id: 'dev',
        path: "./dev", // Path to data on filesystem, relative to site dir.
        routeBasePath: "dev", // URL Route.
        include: ["**/*.md"],
        sidebarPath: require.resolve('./sidebarsDev.js'),
      },
    ],
    [
      "@docusaurus/plugin-content-docs",
      {
        id: 'support',
        path: "./support", // Path to data on filesystem, relative to site dir.
        routeBasePath: "support", // URL Route.
        include: ["**/*.md"],
        sidebarPath: require.resolve('./sidebarsSupport.js'),
      },
    ],
    [
      "@docusaurus/plugin-content-docs",
      {
        id: 'marketing',
        path: "./marketing", // Path to data on filesystem, relative to site dir.
        routeBasePath: "marketing", // URL Route.
        include: ["**/*.md"],
        sidebarPath: require.resolve('./sidebarsMarketing.js'),
      },
    ],
  ],

[slorber]

sorry about that, I keep in mind to write this doc soon :)

[mathetos]

@slorber Not a problem at all, and not a complaint. Just wanted to chime in to validate that it's working and worth some solid docs. V2 really is slick, great work!

[slorber]

Until I document this, note that to version a new plugin instance, a new cli command appear, see docusaurus docs:version:community (community = pluginId of the second instance)