V2: document docs plugin multi-instance

📚 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",
},

[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]

FYI I just added documentation for the multi-instance support.

Can early adopters read it and tell me if something is not clear enough please?

https://v2.docusaurus.io/docs/next/docs-multi-instance/