Skip to content

Fix broken heading links #472

Open
rohitpaulk wants to merge 1 commit into
ghostty-org:mainfrom
rohitpaulk:only-track-duplicate-ids-within-page
Open

Fix broken heading links #472
rohitpaulk wants to merge 1 commit into
ghostty-org:mainfrom
rohitpaulk:only-track-duplicate-ids-within-page

Conversation

@rohitpaulk

@rohitpaulk rohitpaulk commented Jul 10, 2026

Copy link
Copy Markdown

Problem

On https://ghostty.org/docs/features/ssh, the in-page [shell integration](#shell-integration) link is broken. It points to #shell-integration, but the heading on that page actually renders with id="shell-integration-2".

Root cause

In src/lib/docs/remark-heading-ids.mjs, the encounteredIDs Map used to de-duplicate heading IDs is created in the plugin factory scope:

export default function remarkHeadingIds() {
  const encounteredIDs = new Map(); // shared across ALL docs
  return (node) => { ... };
}

Next.js instantiates the remark plugin once (see next.config.mjs) and reuses it for every MDX file, so the counter persists across documents. Multiple docs contain a "Shell Integration" heading (docs/features/ssh.mdx, docs/install/release-notes/1-3-0.mdx, docs/install/release-notes/1-3-1.mdx), so they get slugs like shell-integration-2, shell-integration-3 etc.

Fix

Move the encounteredIDs Map inside the returned per-document transformer so the counter resets for each file.

Validation

Verified with a real npm run build and inspection of the generated static HTML:

  • docs/features/ssh.html: heading id goes from shell-integration-2 to shell-integration (i.e. previously broken link now works)
  • docs/install/build.html (two ### Dependencies headings): still correctly produces dependencies and dependencies-2

@vercel

vercel Bot commented Jul 10, 2026

Copy link
Copy Markdown

@rohitpaulk is attempting to deploy a commit to the Ghostty Team on Vercel.

A member of the Team first needs to authorize it.

@rohitpaulk rohitpaulk changed the title Only track duplicate heading IDs within a page in remarkHeadingIds Fix broken heading links Jul 10, 2026
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