COMDOX-1759: Fix broken anchor links in generated GraphQL API reference - #596
Merged
Conversation
SpectaQL emits type/field cross-references as bare same-page anchors (e.g. `[Cart!](#cart)`), which only worked before the reference was paginated into per-page query/mutation/type chunks. Have generate-spectaql-md.js resolve each link's target heading across all chunks of a schema version and re-point it at the correct page when the target lands elsewhere, leaving genuinely same-page anchors untouched. Regenerated all five schema versions (saas, 2.4.9, 2.4.8, 2.4.7, 2.4.6) with the fix applied. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
dshevtsov
added
bug
Contributor
🔍 Linter ReportClick to expand full reportThis comment was automatically generated by the linter bot. |
dshevtsov
marked this pull request as ready for review
August 4, 2026 00:09
github-project-automation
Bot
moved this from 📋 Needs Review
to 👍 Approved
in Commerce - Pull Requests
github-project-automation
Bot
moved this from 👍 Approved
to 🏁 Done
in Commerce - Pull Requests
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.
Purpose of this pull request
Fixes broken cross-page anchor links in the generated GraphQL API reference pages.
SpectaQL emits every type reference as a bare same-page anchor (e.g.
[Cart!](#cart)). This worked when the full schema lived on one page, but after the reference was split across multiple pages (queries, mutations, types A–B, types C–E, etc.), those bare anchors break whenever the target type lives on a different page than the link.The fix adds two functions to
scripts/generate-spectaql-md.js:collectHeadingPages— builds a map from every### TypeNameheading to the page file that contains itrewriteBareAnchors— rewrites bare(#anchor)links to absolute paths (e.g./reference/graphql/saas/types-a-b.md#attributemetadataresponse) when the anchor's target lives on a different page than the linkAll autogenerated files for versions 2.4.6, 2.4.7, 2.4.8, 2.4.9, and SaaS were regenerated with the fixed links.
Affected pages
All GraphQL API reference pages across all schema versions:
Manual testing
Preview the SaaS GraphQL reference and verify that type links within query/mutation argument tables and response fields navigate to the correct page:
https://adobedocs.github.io/commerce-webapi/commerce/webapi/reference/graphql/saas/