Skip to content

Keep explicit heading ids in the .md export - #94

Merged
kristin-kronstain-brown merged 1 commit into
mainfrom
md-export-heading-ids
Nov 16, 2026
Merged

kristin-kronstain-brown merged 1 commit into
mainfrom
md-export-heading-ids

Conversation

@kristin-kronstain-brown

Copy link
Copy Markdown
Collaborator

Why

The .md output format dropped explicit heading ids. A heading written as ### Install kagent with Helm {#install-kagent-helm} came out of the export as a plain ### Install kagent with Helm. Hextra puts the id on a <span> inside the heading, and transform.HTMLToMarkdown drops it.

In-page links such as [install kagent](#install-kagent-helm) then pointed at nothing in the .md file. The Lychee link check scans the .md exports, so it reported "Cannot find fragment" even though the HTML page was correct. For example, the kagent link check on kagent-dev/website#738 reports four of these warnings (kagent-dev/website#737):

  • kagent/{main,latest}/setup/installation.md#install-kagent-helm
  • kagent/{main,latest}/agents/egress-policies.md#origin-format

What changed

  • layouts/_partials/page-to-markdown.html. Before the HTML-to-Markdown conversion, the partial marks each heading whose id differs from the slug of its text. After the conversion, it restores that id as a {#id} heading attribute. Headings with auto-generated ids are left alone, so the export stays clean.
  • New tests/md-heading-ids.spec.ts, added to the static project's testMatch allowlist in playwright.config.ts.
  • CHANGELOG.md entry under Unreleased.

The Copy as Markdown button (copy-markdown.html) is unchanged.

Testing

  • md-heading-ids.spec.ts passes against the OSS fixture.
  • Built the kagent docs site against this branch. The .md pages now carry {#install-kagent-helm} and {#origin-format}, and an offline Lychee run with --include-fragments over every .md export reports 0 fragment errors.
  • The full static and content suites show the same 25 failures on this branch as on a clean main build.

After merge

Tag a release, then bump the docs-theme-extras pin in consumers (kagent is on v0.5.0) to clear the warnings.

🤖 Generated with Claude Code

Signed-off-by: Kristin Brown <kristin.brown@solo.io>
@kristin-kronstain-brown
kristin-kronstain-brown merged commit 6b015b1 into main Nov 16, 2026
6 checks passed
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