fix(preview-links): honor custom frontmatter id when deriving doc URLs#4937
Merged
Conversation
The docs PR preview-link generator built a page's URL purely from its filename when no `slug` frontmatter was present, ignoring a custom `id`. Docusaurus derives a slug-less doc's URL from the directory path plus its `id` (which defaults to the filename but can be overridden), so any page setting a custom `id` without a `slug` got a wrong preview link. Example: docs/production-deployment/self-hosted-guide/temporal-nexus.mdx sets `id: nexus`, so it publishes at .../self-hosted-guide/nexus, but the generator linked to .../self-hosted-guide/temporal-nexus. extractFrontMatter now also reads `id`, and slug derivation substitutes it for the filename segment (falling back to today's filename/index behavior when no id is set). slug frontmatter still takes precedence. Also moves the BASE_SHA guard into main() so the module's pure helpers can be imported by tests without the process exiting. Adds a test suite covering the id/slug/filename cases.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
📖 Docs PR preview linksThis PR does not change any pages in /docs. If you make updates, links to the modified pages will appear here. |
Duncanma
approved these changes
Jul 21, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The docs PR preview-link generator (
bin/generate-docs-preview-list.js) built a page's URL from its filename when the page had noslugfrontmatter, ignoring a customid. Docusaurus derives a slug-less doc's URL from the directory path plus itsid(which defaults to the filename but can be overridden in frontmatter). So any page that sets a customidwithout asluggot an incorrect preview link.Reported on #4906:
docs/production-deployment/self-hosted-guide/temporal-nexus.mdxsetsid: nexus, so it publishes at.../self-hosted-guide/nexus, but the preview comment linked to.../self-hosted-guide/temporal-nexus.This isn't unique to that PR — it affects every page with a custom
idand noslug(e.g. the SDKset-up.mdxpages withid: set-up-your-local-<lang>, andreferences/client-envrionment-configuration.mdxwhoseidcorrects a filename typo).Changes
extractFrontMatternow also readsid.idfor the last path segment, falling back to the existing filename/indexbehavior when noidis set. Explicitslugfrontmatter still takes precedence (unchanged).BASE_SHAguard intomain()so the module's pure helpers are importable by tests without the process exiting.tests/test-docs-preview-list.mjscovering: custom id override, no-id filename fallback, index handling (with and without a custom id), whitespace id, and slug-wins-over-id precedence.Verification
node tests/run-all.mjspasses (87 tests).temporal-nexus.mdx: it now emits slugproduction-deployment/self-hosted-guide/nexus(was.../temporal-nexus).How the URL rule was validated
Confirmed Docusaurus's id→URL behavior against existing repo pages, not just the reported one: internal links to
develop/go/set-up.mdx(id: set-up-your-local-go) all use the id-based path, and links to the misspelled-filenameclient-envrionment-configuration.mdx(id: client-environment-configuration) all use the id spelling.┆Attachments: EDU-6776 fix(preview-links): honor custom frontmatter id when deriving doc URLs