25

As I know, Docusaurus supports customized pages, but is there a way to have two docs in one Docusaurus project?

The original Navbar items have:

  • Docs
  • Blog
  • ...

I want to have something like this:

  • Docs 1
  • Docs 2
  • Blog
  • ...

I know I can make many subfolders just in one doc, but for some reason, I want a two Docs structure, which gives me a cleaner way to access docs.

If Docusaurus cannot offer this feature currently, I want to ask is there other documentation frameworks offer this feature?

1

6 Answers 6

50

You need to use the plugin-content-docs.

First, create the other docs folder, like docs, docs-api, docs-system.

(1) In your docusaurus.config.js file, configure your "default" docs:

(module.exports = { // start of the module.export declaration
[…]

    presets: [
        [
          '@docusaurus/preset-classic',
          {
            docs: {
              routeBasePath: 'docs',
              path: 'docs',
              sidebarPath: require.resolve('./sidebars.js'),
              lastVersion: 'current',
              onlyIncludeVersions: ['current'],
            },
            theme: {
              customCss: require.resolve('./src/css/custom.css'),
            },
          },
        ],
      ],

[…] 
}); // end of the module-export declaration

(2) Now, the magic!: in the same file, configure your other documents:

(module.exports = { // start of the module.export declaration
[…]

plugins: [
    […]
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'docs-api',
        path: 'docs-api',
        routeBasePath: 'docs-api',
        sidebarPath: require.resolve('./sidebars.js'),
      }, 
    ],
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'docs-system',
        path: 'docs-system',
        routeBasePath: 'docs-system',
        sidebarPath: require.resolve('./sidebars.js'),
      }, 
    ],
],

[…]
}); // end of the module-export declaration

(3) Now you probably want these documents in your NavBar, right? So add then!

(module.exports = { // start of the module.export declaration
[…]

navbar: {
  hideOnScroll: true,
  title: 'your title',
  logo: {
    alt: '',
    src: 'img/favicon.ico',
  },
  items: [
    {
      to: '/docs/Intro',    // ./docs/Intro.md
      label: 'Docs Title',
      position: 'left',
      activeBaseRegex: `/docs/`,
    },
    {
      to: '/docs-api/Intro',    // ./docs-api/Intro.md
      label: 'API',
      position: 'left',
      activeBaseRegex: `/docs-api/`,
    },
    {
      to: '/docs-system/Introducao',  // ./docs-system/Intro.md
      label: 'My System',
      position: 'left',
      activeBaseRegex: `/docs-system/`,
    },
  ],
},

[…]
}); // end of the module-export declaration

IMPORTANT

Sometimes you will modify your docusaurus.config.js and will not "work", so close the docusaurus service (just Ctrl+C in your terminal/power shell) and restart it -- I could have saved a few hours if a had known this before.

If you don't have the plugin-content-docs plugin, just install it:

npm install --save @docusaurus/plugin-content-docs


ROADMAP

I had a hard time figuring this out. What I did was download the whole docusaurus project, get the website part, trim everything that I did not need and this is what I got.


REFERENCES (Update 2022/03/02)

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

5
  • 2
    This answer deserves more credit, THANK YOU!! Commented Sep 9, 2021 at 9:30
  • 1
    You saved me so much time!
    – Poeta Kodu
    Commented Sep 25, 2021 at 23:11
  • 2
    Thank you. Gave me the right direction. I had to also use docsPluginId with docId in order for this to work in the navbar.
    – elpddev
    Commented Oct 9, 2021 at 15:44
  • 2
    This is officially documented here: docusaurus.io/docs/docs-multi-instance Commented Mar 2, 2022 at 10:30
  • Note that additional instances need to point toward unique docs, aka, make sure you specify unique sidebar-<subinstance>.js files for each instance.
    – Zenahr
    Commented Jan 3, 2023 at 14:52
10

This solution worked for me. Using the 'autogenerated' sidebar in Docusaurus v2.0.0-beta.15

sidebars.js

/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */

const sidebars = {

  // tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],
  newone: [{type: 'autogenerated', dirName: 'newone'}],  // foldername
  newtwo: [{type: 'autogenerated', dirName: 'newtwo'}],  // foldername

};

module.exports = sidebars;

docusaurus.config.js

      navbar: {
        title: 'My Site',
        logo: {
          alt: 'My Site Logo',
          src: 'img/logo.svg',
        },
        items: [
          // {
          //   type: 'doc',
          //   docId: 'intro',
          //   position: 'left',
          //   label: 'Tutorials',
          // },

          {
            type: 'docSidebar',  // docSidebar
            position: 'left',
            sidebarId: 'newone', // foldername
            label: 'NEWONE',     // navbar title
          },
          {
            type: 'docSidebar',  // docSidebar
            position: 'left',
            sidebarId: 'newtwo', // foldername
            label: 'NEWTWO',     // navbar title
          },

          {to: '/blog', label: 'Blog', position: 'left'},
          {
            href: 'https://github.com/facebook/docusaurus',
            label: 'GitHub',
            position: 'right',
          },
        ],
      },

Your docs folder:

docs/
    newone/
        intro.md
    newtwo/
        intro.md
4
  • Perfect answer! Thanks Commented Apr 13, 2022 at 19:28
  • This works great but, is there a way to avoid adding labels to navbar? skipping the label still adds it. Commented Dec 10, 2023 at 14:50
  • Consice and working solution in Docusaurus 3.4.0. Thanks!
    – Apogentus
    Commented Jul 2 at 15:09
  • One bad thing of this method is that docs/ is appended, docs/newone, docs/newtwo. How to remove the /docs part?
    – rtxa
    Commented Aug 8 at 19:12
1

I tried this way and it's working.

[Edit 1]: But when I select API then both API and Docs in Navbar becomes green. Can you tell us what's the reason behind this @Yangshun Tay and can you suggest the edit for that?

[Edit 2]: I read the documentation, it's written in @docusaurus/theme-classic, if we set activeBasePath property then links with that common path (docs in this case) will have active attribute.

sidebar.js

module.exports = {
    someSidebar: {
        Docusaurus: ['doc1', 'doc2'],
        Features: ['doc3']
    },
    someOtherSidebar: {
        Test: ['mdx']
    }
};

docusaurus.config.js

The navbar links are like this -

links: [
    {
        to: 'docs/doc1',
        // activeBasePath: 'docs', // [Edit 3]
        label: 'Docs',
        position: 'left'
    },
    {
        to: 'docs/mdx',
        label: 'API',
        position: 'left'
    },
]

Folder structure of docs folder is like this -

docs
├── docs1.md
├── mdx.md
0

Regardless of whether you're using v1 or v2, the sidebars.js configuration can contain multiple keys, each having its own sidebar.

6
  • 2
    I think he meant something else, with the help of sidebars.js we can create multiple partitions inside the /docs route. But what he is asking for is to create two separate docs folder API and docs which have the same functionality as docs. It is present in v1 of docusaurus navbar. Commented Mar 21, 2020 at 17:18
  • He meant navbar Commented Mar 21, 2020 at 17:21
  • Navbar items are just hrefs and you are free to put anything you want in it. Commented Mar 21, 2020 at 17:37
  • What if I want a News page which is exactly similar to blog page, is it possible to create one in v2? I tried by creating a folder named news and moving the .mdx files inside it. It didn't work Commented Mar 21, 2020 at 17:45
  • 1
    Ja! What GermaVinsmoke said is exactly what I mean. @YangshunTay I understand Navbar items are just hrefs and I can customize it. But the doc generation is automatic, including all the routes and the sidebar. I can create a new PAGE and put on navbar, but how can I create another new doc which has a different sidebar?
    – Echo Yang
    Commented Mar 22, 2020 at 7:05
0

You need to use the doc type in docusaurus config. I think the "to" type is for pages not docs.

To make the sidebar correct, you need to also set the activeSidebarClassName value in the config to let it know which sidebar (among those you exported in the sidebars.js) you want to use for this doc.

activeSidebarClassName: 'navbar__link--active',

https://docusaurus.io/docs/api/themes/configuration#navbar-doc-link

0

Setting up Docusaurus to be multi-instance spans changes across many files. To make it easier to set up, I've created a base install with all the necessary changes to go multi-instance, and have released it as a GitHub template.

Fork it here:
mg0716/docusaurus-multi

Many of the changes in this repo were a result from @d-kastier's original comment.

Very open to feedback and pull requests, so feel free to give it a shot!

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.