Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Setting id frontmatter unexpectedly affects the published path of a document #10496

Open
2 tasks done
chriswhong opened this issue Sep 12, 2024 · 2 comments
Open
2 tasks done
Labels
documentation The issue is related to the documentation of Docusaurus

Comments

@chriswhong
Copy link

Have you 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

  • I'd be willing to address this documentation request myself.
@chriswhong chriswhong added documentation The issue is related to the documentation of Docusaurus status: needs triage This issue has not been triaged by maintainers labels Sep 12, 2024
@Josh-Cena
Copy link
Collaborator

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 slorber removed the status: needs triage This issue has not been triaged by maintainers label Sep 13, 2024
@slorber
Copy link
Collaborator

slorber commented Sep 13, 2024

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation The issue is related to the documentation of Docusaurus
Projects
None yet
Development

No branches or pull requests

3 participants