duplicate route detection with autogenerated slugs

[ArthurFlag]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Prerequisites

• I'm using the latest version of Docusaurus.
• I have tried the npm run clear or yarn clear command.
• I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
• I have tried creating a repro with https://new.docusaurus.io.
• I have read the console error message carefully (if applicable).

Description

I'm trying to diagnose a duplicated route warning, and I'm not sure what the problem is, I suspect it's a bug.

Reproducible demo

https://codesandbox.io/p/devbox/pensive-neumann-8hhhvs

Steps to reproduce

1. Create a file structure with similar file names, but in different folders. So different ids.

   

2. Add them in a TOC with the autogenerated instruction:

 {
      type: "category",
      label: "service",
      link: {
        id: "tools/cli/service",   // This is like the one below but that's a file.
        type: "doc",
      },
      items: [
        {
          type: "autogenerated",
          dirName: "tools/cli/service", // That's a directory, not a file.
        },
      ],
    },

3. Build and get a duplicated route warning:

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

In my case, there is only 1 file, or page, living there (see repro) but I do have a folder with the same path.

Expected behavior

I shouldn't see a warning, since there is no file path duplication. Only one page will be rendered at that location.

Actual behavior

I get a duplicated route warning.

Your environment

• Docusaurus version used: 3.1
• Environment name and version (e.g. Chrome 89, Node.js 16.4):
• Operating system and version (e.g. Ubuntu 20.04.2 LTS):

Self-service

• I'd be willing to fix this bug myself.

[Josh-Cena]

Hi, service/service.md will also become /service. If you want to make its slug be service/service, you have to use the slug front matter. I'll add a sentence to the doc.

[muuki88]

Hi 😄

I have a smiliar issue with the typescript api docs plugin. It generates modules.md by default. I have a folder called modules where this is being generated. I tried to be smart and implemented a custom isCategoryIndex function like this

async sidebarItemsGenerator({ defaultSidebarItemsGenerator, ...args }) {
  return defaultSidebarItemsGenerator({
    ...args,
    // by default docusaurus treats a file named as the parent directory as the index file as well, which
    // collides with the modules.md generated by the typescript API docs.
    // see https://docusaurus.io/docs/sidebar/autogenerated#category-index-convention
    isCategoryIndex({ fileName, directories }) {
      const eligibleDocIndexNames = ['index', 'readme'];
      return eligibleDocIndexNames.includes(fileName.toLowerCase());
    }
  });
}

as described here in the docs: https://docusaurus.io/docs/sidebar/autogenerated#category-index-convention

The function is working and the categorization as well. However the warning still exists. Is the warning generated independently from the isCategoryIndex function?

I cross posted this here: typedoc2md/typedoc-plugin-markdown#647

[slorber]

@muuki88 we are not the implementor of the typedoc plugin and don't really know how it works internally.

Note that there are 2 things to be aware of:

• The category index convention defines if clicking the sidebar category links to the doc
• The category index convention does not affect the doc URL (as far as I remember)

In your case, even though you define isCategoryIndex, you still have modules/index.md and modules/modules.md competing for the same URL, which is what the warning report.

If you want to alter the doc URL, you can use the slug front matter.

If the typedoc plugin does not enable you to inject a slug front matter, you can try to make an exception with the parseFrontMatter hook: https://docusaurus.io/docs/markdown-features#front-matter

The warning should disappear once Docusaurus sees that both docs are exposed on 2 distinct URLs. It's here for a reason: currently one of your 2 docs is probably inaccessible.

[muuki88]

Hi @slorber

Thanks for the quick and detailed reply ❤️ Makes sense if both are still competing for the same URL. Seems I didn't fully comprehend what the isCategoryIndex function does 🙈

I'll move the discussion to the typedoc-plugin-markdown forum. Should be possible to customize either the modules.md filename or inject custom fontmatter meta data.

And thanks for your great React Newsletter 🤩

[slorber]

Sure 👍

Note that parseFrontMatter is a core feature, so technically you can still use it to inject custom front matter in other plugins that use our mdx loader. I think that typedoc plugin is "reusing" our docs plugin so it qualifies too. I admit it's not the most convenient to solve this problem, a bit low level, but it should still work.