Create a new docs page using Docusaurus v2

Question

I'm trying Docusaurus v2 and I would like to have two different docs pages: one for documentation and one for API.

This is my files structure:

docusaurus.config.js

module.exports = {
  title: 'My Site',
  tagline: 'The tagline of my site',
  url: 'https://your-docusaurus-test-site.com',
  baseUrl: '/',
  onBrokenLinks: 'throw',
  favicon: 'img/favicon.ico',
  organizationName: 'facebook', // Usually your GitHub org/user name.
  projectName: 'docusaurus', // Usually your repo name.
  themeConfig: {
    navbar: {
      title: 'My Site',
      logo: {
        alt: 'My Site Logo',
        src: 'img/logo.svg',
      },
      items: [
        {
          to: 'docs/documentation',
          activeBasePath: 'docs',
          label: 'Documentation',
          position: 'left',
        },
        {
          to: 'docs/api',
          activeBasePath: 'docs',
          label: 'API',
          position: 'left',
        },
        { to: 'blog', label: 'Blog', position: 'left' },
        {
          href: 'https://github.com/facebook/docusaurus',
          label: 'GitHub',
          position: 'right',
        },
      ],
    },
    footer: {
      style: 'dark',
      links: [
        {
          title: 'Docs',
          items: [
            {
              label: 'Style Guide',
              to: 'docs/',
            },
            {
              label: 'Second Doc',
              to: 'docs/doc2/',
            },
          ],
        },
        {
          title: 'Community',
          items: [
            {
              label: 'Stack Overflow',
              href: 'https://stackoverflow.com/questions/tagged/docusaurus',
            },
            {
              label: 'Discord',
              href: 'https://discordapp.com/invite/docusaurus',
            },
            {
              label: 'Twitter',
              href: 'https://twitter.com/docusaurus',
            },
          ],
        },
        {
          title: 'More',
          items: [
            {
              label: 'Blog',
              to: 'blog',
            },
            {
              label: 'GitHub',
              href: 'https://github.com/facebook/docusaurus',
            },
          ],
        },
      ],
      copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`,
    },
  },
    presets: [
      [
        '@docusaurus/preset-classic',
        {
          docs: {
            sidebarPath: require.resolve('./sidebars.js'),
            // Please change this to your repo.
            editUrl: 'https://github.com/facebook/docusaurus/edit/master/website/',
          },
          blog: {
            showReadingTime: true,
            // Please change this to your repo.
            editUrl: 'https://github.com/facebook/docusaurus/edit/master/website/blog/',
          },
          theme: {
            customCss: require.resolve('./src/css/custom.css'),
          },
        },
      ],
    ],
}

sidebars.js

module.exports = {
  documentation: {
    Example: ['documentation/documentation1'],
    // Docusaurus: ['doc1', 'doc2', 'doc3'],
    // Features: ['mdx'],
  },
  api: {
    'Color formats': ['api/api1'],
  },
}

documentation1.md

---
id: documentation1
title: Documentation 1
sidebar_label: Style Guide
slug: /
---

...

api1.md

---
id: api1
title: Api 1
sidebar_label: Style Guide
slug: /
---

...

But it doesn't work. When I click on Documentation button, it goes to localhost:3000/docs/documentation and I get Page Not Found. When I click on API button, it goes to localhost:3000/docs/api and I get the same error. If I go to /localhost:3000/docs/, I see the api1 markdown file content.

I also get this warning:

warn Duplicate routes found!
Attempting to create page at /docs/, but a page already exists at this route
Attempting to create page at /docs/, but a page already exists at this route
This could lead to non-deterministic routing behavior

What I'm doing wrong?

I simply would like to have a button Documentation that links to /documentation and the button API that links to /api.

I think I have to modify something here but I don't know what:

presets: [
  [
    '@docusaurus/preset-classic',
    {
      docs: {
        sidebarPath: require.resolve('./sidebars.js'),
        // Please change this to your repo.
        editUrl: 'https://github.com/facebook/docusaurus/edit/master/website/',
      },
      blog: {...},
      theme: {...},
    },
  ],
],

I read the documentation and I searched on Google but nothing helped me.

Answer 1

All docs are under /docs/ path by default. Sidebars do not affect routes.

You created 2 docs that have slug / so they both have /docs/ as the final route.

You should rather use slug: /api and link to /docs/api

If you really want /api there's a docs-only option to remove the/docs/ path prefix

Answer 2

The secret is to use the doc type in docusarus config, and set

activeSidebarClassName: 'navbar__link--active',

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