Custom Tag Page in Docusaurus

Question

I want to create a custom Tag Page for docusaurus. I am using the classic theme and successfully swizzled DocTagDocListPage. So now I can change the template for all tag pages.

What I want to do is have a custom markdown page for the route docs/tags/contribute e.g. It would be great to just create that file in docs/tags/contribute.md to have that page but docusaurus is complaining with the following warning.

[WARNING] Duplicate routes found!
- Attempting to create page at /docs/tags/contribute, but a page already exists at this route.
This could lead to non-deterministic routing behavior.

Is there an easy way to setup that page without having to write my own theme? Or for my markdown page to take precedence over the theme route?

Answer 1

Since you have already created a page for /docs/tags by swizzling DocTagDocListPage, you can use the plugin-content-pages plugin to create a custom page for /docs/tags/contribute.

First, install the plugin-content-pages package:

npm install @docusaurus/plugin-content-pages

Then, you need to configure yout docusaurus.config.js file:

module.exports = {
  // ...
  plugins: [
    [
      "@docusaurus/plugin-content-pages",
      {
        id: "tags-contribute",
        path: "tags/contribute",
        routeBasePath: "docs",
      },
    ],
  ],
};

This configuration tells Docusaurus to generate a page with the ID tags-contribute for the markdown file located at docs/tags/contribute.md, and to use the /docs route base path.

Now you can create the docs/tags/contribute.md file. and Docusaurus will generate a page for /docs/tags/contribute with the content from docs/tags/contribute.md.

Keep in mind that if you have conflicting routes, Docusaurus will put priority on the one which appears first in your configuration. In this case, since the DocTagDocListPage was already swizzled, you can be assured that your custom page will take precedence.