Setting `id` frontmatter unexpectedly affects the published path of a document

[chriswhong]

Have you read the Contributing Guidelines on issues?

• [X] I have read the Contributing Guidelines on issues.

Description

We recently discovered that setting id in the frontmatter has the same effect as setting slug, specifically it will set the path of the document to /{id} instead of /{filename}.

The documentation describes this value as "A unique document ID.", and does not mention this important side effect.

I was able to track this down to https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-plugin-content-docs/src/docs.ts#L143, but I am still unclear about the intent of reading frontMatter.id here and using it instead of unprefixedFilename if it exists.

So, I am not sure if this is a bug, or a documentation issue. I think if there's already a way to override using the filename as the path (by setting slug frontmatter), setting id should not also change it. If this is intentional for whatever reason, we should update the documentation to mention that setting this will also change the path.

Self-service

• [X] I'd be willing to address this documentation request myself.

[Josh-Cena]

My thinking is that it should not affect the slug, but I'm sure there's someone relying on this behavior. Perhaps we should document it and recommend using parseFrongMatter to inject slug overrides.

[slorber]

To me, this is a documentation issue on a historical behavior. We may revisit the behavior but after all these years you are the first to open an issue, so I guess it must be fine 😄

Changing the behavior would be a breaking change, so it's better to document it for now.

I guess we could mention that here: https://docusaurus.io/docs/create-doc#doc-urls

If you want stable URLs, you'd rather always use slug. Our doc should probably advise that, because it's easy to rename a file or change the id and break a link.