fix: keep underscores in identifier heading anchors - #400
Merged
Merged
Conversation
marc0olo
added this pull request to stack #402
September 18, 2026 12:05
marc0olo
marked this pull request as draft
September 18, 2026 12:11
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
The regex handling still diverges from CommonMark for nested underscores and multi-backtick code spans.
Get a fresh assessment by requesting another Copilot review.
Pull request overview
Updates anchor validation to better match Starlight-generated heading IDs, especially for identifiers containing underscores.
Changes:
- Separates asterisk and underscore emphasis handling.
- Protects inline code and unwraps links before slug generation.
- Updates shared anchor logic used by validation and static-site synchronization.
Verified: Reviewed the changed helper, its callers, and the configured Markdown pipeline.
File summaries
| File | Description |
|---|---|
scripts/lib/anchors.mjs |
Revised rendered-heading text and slug extraction logic. |
Review details
Suppressed comments (1)
scripts/lib/anchors.mjs:31
- This split recognizes only code spans delimited by exactly one backtick. CommonMark permits matching runs of multiple backticks, so a heading with a two-backtick code span around
_literal_keeps those underscores literal in the rendered heading, while this code exposes them toUNDERSCORE_EMPHASISand computes a different anchor. Use a delimiter-run-aware code-span scanner or the Markdown AST before applying the emphasis rules.
.split(/(`[^`]*`)/g)
- Files reviewed: 1/1 changed files
- Comments generated: 1
- Review effort level: Lite
💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
marc0olo
force-pushed
the
infra/anchor-slug-code-spans
branch
from
September 18, 2026 13:24
e7c1656 to
15e833f
Compare
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
The parser does not enable the site's GFM extensions, so some supported headings can receive different anchor IDs.
Get a fresh assessment by requesting another Copilot review.
Review details
- Files reviewed: 2/3 changed files
- Comments generated: 1
- Review effort level: Lite
marc0olo
force-pushed
the
infra/anchor-slug-code-spans
branch
from
September 18, 2026 13:47
15e833f to
8faa33d
Compare
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Script-only mdast packages should follow the existing convention and be moved to devDependencies.
Get a fresh assessment by requesting another Copilot review.
Review details
- Files reviewed: 2/3 changed files
- Comments generated: 1
- Review effort level: Lite
Identifier headings with two or more underscores were mis-slugged, which failed validate on a correct link.
marc0olo
force-pushed
the
infra/anchor-slug-code-spans
branch
from
September 18, 2026 14:07
8faa33d to
d0ce553
Compare
marc0olo
marked this pull request as ready for review
September 18, 2026 14:19
lwshang
approved these changes
Sep 21, 2026
marc0olo
added a commit
that referenced
this pull request
Sep 21, 2026
…#401) ## Summary Stacked on #400. Three changes to the static-site sync. - **Pages land verbatim.** The `dfx` translation and the brand normalizations are gone. Link mapping, the `source_repo` / `source_ref` frontmatter and the do-not-edit marker stay. - **Banned content stops the sync** (em dash, en-dash separator, `dfx`), naming the page, for upstream to fix. Softer house style is reported only. - **The workflow takes an optional `ref`** (sha, tag or branch) to sync a docs fix that upstream has shipped but not released. Dispatching the pinned release is a no-op; a ref behind the pin runs but warns that the pin moves backwards. - **A release that changes no page opens no PR**, unless the pin is a commit, where moving it onto a tag is the point. - `.agents/upstream-tracking.md` updated to match. Verified at `59641fc`: output byte-identical to the eight upstream files apart from the marker, two provenance fields and three link rewrites; `validate` and `build` pass. The sync itself is not included. Merge this, then dispatch with `ref=59641fc`.
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
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
npm run validatefails onmainfor a correct link: the slug library mis-slugged any identifier heading with two or more underscores (flexible_http_requestbecameflexiblehttprequest,canister_inspect_messagelikewise).renderedTextparses the heading withmdast-util-from-markdownandmdast-util-to-string, replacing the regexes that approximated inline markdown#markers included, so1. Create a target canisterkeeps its numberdevDependencies; the lockfile root is hand-edited rather than regeneratedVerified against a built site: every heading id in
dist/matches the library across all 200 pages, both directions. A footnote reference in a heading stays out of reach, noted in the code.