Skip to content

fix(docs): repair anchor broken by em-dash-to-hyphen sweep - #245

Open
marcelo-maciel wants to merge 1 commit into
fullstackhero:mainfrom
marcelo-maciel:docs/fix-broken-anchors
Open

fix(docs): repair anchor broken by em-dash-to-hyphen sweep#245
marcelo-maciel wants to merge 1 commit into
fullstackhero:mainfrom
marcelo-maciel:docs/fix-broken-anchors

Conversation

@marcelo-maciel

Copy link
Copy Markdown
Contributor

Root cause

Commit a96478c (style: replace all em dashes with hyphens across the site) replaced every em dash () with a hyphen (-) site-wide. github-slugger (the same library Astro/Starlight use to generate heading anchors) drops em dashes entirely when slugging, but keeps hyphens as-is. That means the sweep silently changed the anchor for any heading that contained an em dash:

heading slug
Chat — the realtime showcase (before) chat--the-realtime-showcase (2 hyphens)
Chat - the realtime showcase (after) chat---the-realtime-showcase (3 hyphens)

Any internal link pointing at the old slug broke silently. astro check does not validate anchors inside link targets, so it passed with 0 errors both before and after the sweep, on both the broken and fixed link.

Fix

src/content/docs/frontend/architecture.mdx linked to the "Chat - the realtime showcase" heading in dashboard.mdx using the pre-sweep slug. Updated the link to the current slug. The heading text itself is untouched, so the public heading and its URL fragment stay consistent with the rest of the post-sweep site (no new em dash introduced).

Verification method

  1. Extended a link-anchor checker (walks src/content/docs, computes slugs per file with the site's actual github-slugger dependency, and resolves every internal anchor link against them) to also cover same-file relative anchors (](#anchor)), not just cross-file ones (](/docs/route#anchor)). Total anchor-bearing links found across the site: 5. Before the fix, 1 was broken (the one described above); after, 0.
  2. Before trusting the "new" slug, reproduced the old slug first by running the site's own github-slugger against the original em-dash heading text (Chat — the realtime showcase) and confirmed it produced byte-for-byte the same anchor (chat--the-realtime-showcase) that was in the broken link. Only after that check matched did I trust the slugger's output for the new heading text.
  3. npx astro check -> 0 errors, 0 warnings (21 pre-existing hints, unrelated to this change).

Scope

Single link fix, no heading text changed (would break the public URL and any external link), no prose rewritten. Not touching npm run build, which fails in buildEnd fetching a font from fonts.gstatic.com — same failure on unmodified main, unrelated to this change.

commit a96478c replaced all em dashes with hyphens site-wide, which
changed the github-slugger output for headings containing em dashes
(the slugger drops em dashes but keeps hyphens, so hyphen count in the
slug changes). The link to the "Chat - the realtime showcase" heading
in dashboard.mdx still pointed at the old two-hyphen slug and silently
broke, since astro check does not validate in-content anchors.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant