Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,14 @@ deliberately, one PR at a time. Never use floating refs in production hugo confi

---

## [Unreleased]

### Fix — the `.md` export dropped explicit heading ids (`layouts/_partials/page-to-markdown.html`, `tests/md-heading-ids.spec.ts`, `playwright.config.ts`)

A heading written as `### Install kagent with Helm {#install-kagent-helm}` came out of the `.md` output format as a plain `### Install kagent with Helm`, because 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, and the Lychee link check, which scans the `.md` exports, reported "Cannot find fragment" (kagent-dev/website#737, see https://kagent.dev/docs/kagent/main/setup/installation.md). The partial now restores the id as a `{#id}` heading attribute when it differs from the slug of the heading text, and leaves headings with auto ids alone so the export stays clean. Verified with the new `md-heading-ids.spec.ts` against the OSS fixture, and by building 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. The Copy as Markdown button (`copy-markdown.html`) is unchanged.

---

## [0.5.1] — 2026-11-13

### Fix — section pages dropped their Enterprise, Alpha, Beta, Open Source, and Experimental badges under the H1 (`layouts/docs/list.html`, `layouts/docs/single.html`, new `layouts/_partials/components/page-badges.html`, `fixture/content/en/test/v2/nav-group/_index.md`, `tests/static.spec.ts`, `tests/slot-order.spec.ts`)
Expand Down
29 changes: 29 additions & 0 deletions layouts/_partials/page-to-markdown.html
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,29 @@
partial for the rationale. */ -}}
{{- $html = $html | replaceRE `(?s)<div[^>]*data-alert-copyas="([^"]*)"[^>]*>\s*<p[^>]*hx:font-medium[^>]*>.*?</p>\s*<div[^>]*>\s*<div[^>]*>(.*?)<span data-alert-md-end></span>\s*</div>\s*</div>\s*</div>` "<blockquote><p>[!$1]</p>$2</blockquote>" -}}

{{- /* Explicit heading ids. Hextra puts the id on a <span> inside the heading,
and transform.HTMLToMarkdown drops it, so a `## Title {#custom-id}`
heading comes out as plain `## Title`. In-page links such as
`[x](#custom-id)` then point at nothing in the .md file, and link checkers
(Lychee) fall back to the heading-text slug and report a broken fragment.
When the id differs from the slug that the heading text would produce,
mark the heading with a placeholder and restore it below as a
`{#custom-id}` heading attribute. Headings whose id equals the slug are
left alone so the export stays clean. */ -}}
{{- $headingIDs := slice -}}
{{- range findRE `(?s)<h[1-6]\b[^>]*>.*?</h[1-6]>` $html -}}
{{- $h := . -}}
{{- with findRESubmatch `\bid="([^"]+)"` $h 1 -}}
{{- $id := index (index . 0) 1 -}}
{{- $text := $h | plainify | htmlUnescape | strings.TrimSpace -}}
{{- if ne $id (anchorize $text) -}}
{{- $marked := replaceRE `(</h[1-6]>)$` (printf "XHEADINGIDPLACEHOLDER%dX${1}" (len $headingIDs)) $h -}}
{{- $headingIDs = $headingIDs | append $id -}}
{{- $html = replace $html $h $marked 1 -}}
{{- end -}}
{{- end -}}
{{- end -}}

{{- $md := $html | transform.HTMLToMarkdown -}}

{{- /* Restore GFM tables before the link/punctuation passes below so table-cell
Expand All @@ -100,6 +123,12 @@
{{- /* Remove empty heading-permalink anchors. */ -}}
{{- $md = $md | replaceRE `\[\]\(#[^)]+\)` "" -}}

{{- /* Restore explicit heading ids marked above. Runs after the empty
permalink anchors are gone so the attribute ends the heading line. */ -}}
{{- range $i, $id := $headingIDs -}}
{{- $md = $md | replaceRE (printf `[ \t]*XHEADINGIDPLACEHOLDER%dX` $i) (printf " {#%s}" $id) -}}
{{- end -}}

{{- /* Normalize smart punctuation to ASCII so the markdown is
easier to diff and friendlier to non-Unicode-aware consumers. */ -}}
{{- $md = $md | replaceRE `[“”]` `"` -}}
Expand Down
2 changes: 1 addition & 1 deletion playwright.config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -98,7 +98,7 @@ export default defineConfig({
{
name: "static",
testMatch:
/static\.spec\.ts$|versioning\.spec\.ts$|versioned-image-auto\.spec\.ts$|version-nested-list\.spec\.ts$|version-inside-fence\.spec\.ts$|version-table-row\.spec\.ts$|version-cards\.spec\.ts$|version-section-banner\.spec\.ts$|shortcode-contexts\.spec\.ts$|conditional-block\.spec\.ts$|conditional-section\.spec\.ts$|cond-reuse-table\.spec\.ts$|reuse-version-remap\.spec\.ts$|llms-directive\.spec\.ts$|llms-index\.spec\.ts$|callout-in-table-cell\.spec\.ts$|callout-in-reuse-tab\.spec\.ts$|auto-cards\.spec\.ts$|card-image\.spec\.ts$|presence\.spec\.ts$|github-shortcode\.spec\.ts$|github-yaml-shortcode\.spec\.ts$|language-switch\.spec\.ts$|redirect\.spec\.ts$|sidebar-linktitle\.spec\.ts$|sidebar-flat\.spec\.ts$|link-hextra-apiref\.spec\.ts$|link-hextra-shapes\.spec\.ts$|dev-subpath-baseurl\.spec\.ts$|build-resilience\.spec\.ts$|hugo-version-floor\.spec\.ts$|page-feedback\.spec\.ts$|footnotes-after-cards\.spec\.ts$|callout-icon\.spec\.ts$|custom-alert\.spec\.ts$|docs-tabs\.spec\.ts$|width-class-default\.spec\.ts$|meta-description\.spec\.ts$|link-hextra-lang-prefix\.spec\.ts$|link-hextra-lts-version\.spec\.ts$|warn-missing-description\.spec\.ts$|search-visible-versions\.spec\.ts$|version-noindex\.spec\.ts$|version-linkversion\.spec\.ts$|version-entry-product\.spec\.ts$|related-docs\.spec\.ts$|section-landing\.spec\.ts$|breadcrumb-labels\.spec\.ts$|section-selector\.spec\.ts$|section-nested-versions\.spec\.ts$|section-versionless\.spec\.ts$|nosections-condition\.spec\.ts$|section-dropdown-title\.spec\.ts$|card-path\.spec\.ts$|tab-code-fences\.spec\.ts$|callout-fence\.spec\.ts$|reuse-list-continuation\.spec\.ts$|source-filters-reuse\.spec\.ts$|override-parity\.spec\.ts$|gate-containment\.spec\.ts$|gate-transparency\.spec\.ts$|gate-normalize\.spec\.ts$|gate-blockhtml\.spec\.ts$|gate-tabs\.spec\.ts$|docs-coverage\.spec\.ts$|file-nil-guard\.spec\.ts$|navbar-title-utility\.spec\.ts$|tab-flatten\.spec\.ts$|tabs-nested\.spec\.ts$|gloss-link\.spec\.ts$|book-document\.spec\.ts$|pdf-download-flat\.spec\.ts$|slot-order\.spec\.ts$|test-status-badge\.spec\.ts$|sitemap-absolute\.spec\.ts$|sitemap-sync\.spec\.ts$|changelog-toolbar\.spec\.ts$|change-highlights\.spec\.ts$/,
/static\.spec\.ts$|versioning\.spec\.ts$|versioned-image-auto\.spec\.ts$|version-nested-list\.spec\.ts$|version-inside-fence\.spec\.ts$|version-table-row\.spec\.ts$|version-cards\.spec\.ts$|version-section-banner\.spec\.ts$|shortcode-contexts\.spec\.ts$|conditional-block\.spec\.ts$|conditional-section\.spec\.ts$|cond-reuse-table\.spec\.ts$|reuse-version-remap\.spec\.ts$|llms-directive\.spec\.ts$|llms-index\.spec\.ts$|callout-in-table-cell\.spec\.ts$|callout-in-reuse-tab\.spec\.ts$|auto-cards\.spec\.ts$|card-image\.spec\.ts$|presence\.spec\.ts$|github-shortcode\.spec\.ts$|github-yaml-shortcode\.spec\.ts$|language-switch\.spec\.ts$|redirect\.spec\.ts$|sidebar-linktitle\.spec\.ts$|sidebar-flat\.spec\.ts$|link-hextra-apiref\.spec\.ts$|link-hextra-shapes\.spec\.ts$|dev-subpath-baseurl\.spec\.ts$|build-resilience\.spec\.ts$|hugo-version-floor\.spec\.ts$|page-feedback\.spec\.ts$|footnotes-after-cards\.spec\.ts$|callout-icon\.spec\.ts$|custom-alert\.spec\.ts$|docs-tabs\.spec\.ts$|width-class-default\.spec\.ts$|meta-description\.spec\.ts$|link-hextra-lang-prefix\.spec\.ts$|link-hextra-lts-version\.spec\.ts$|warn-missing-description\.spec\.ts$|search-visible-versions\.spec\.ts$|version-noindex\.spec\.ts$|version-linkversion\.spec\.ts$|version-entry-product\.spec\.ts$|related-docs\.spec\.ts$|section-landing\.spec\.ts$|breadcrumb-labels\.spec\.ts$|section-selector\.spec\.ts$|section-nested-versions\.spec\.ts$|section-versionless\.spec\.ts$|nosections-condition\.spec\.ts$|section-dropdown-title\.spec\.ts$|card-path\.spec\.ts$|tab-code-fences\.spec\.ts$|callout-fence\.spec\.ts$|reuse-list-continuation\.spec\.ts$|source-filters-reuse\.spec\.ts$|override-parity\.spec\.ts$|gate-containment\.spec\.ts$|gate-transparency\.spec\.ts$|gate-normalize\.spec\.ts$|gate-blockhtml\.spec\.ts$|gate-tabs\.spec\.ts$|docs-coverage\.spec\.ts$|file-nil-guard\.spec\.ts$|navbar-title-utility\.spec\.ts$|tab-flatten\.spec\.ts$|tabs-nested\.spec\.ts$|gloss-link\.spec\.ts$|book-document\.spec\.ts$|pdf-download-flat\.spec\.ts$|slot-order\.spec\.ts$|test-status-badge\.spec\.ts$|sitemap-absolute\.spec\.ts$|sitemap-sync\.spec\.ts$|changelog-toolbar\.spec\.ts$|change-highlights\.spec\.ts$|md-heading-ids\.spec\.ts$/,
},
// Consumer-content specs. Every spec here reads the CONSUMER's own content
// — either the built HTML tree (target.builtRoot) or the markdown source
Expand Down
42 changes: 42 additions & 0 deletions tests/md-heading-ids.spec.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
import { test, expect } from "@playwright/test";
import path from "node:path";
import { TEST_PRODUCT_ROOT, readFixture } from "./helpers/fixture";
import { target } from "./helpers/target";

// Regression guard for explicit heading ids in the .md output format
// (utils/page-to-markdown.html).
//
// transform.HTMLToMarkdown drops the id that Hextra puts on the <span> inside a
// heading, so `## Title {#custom-id}` used to come out as plain `## Title`. Any
// in-page `[x](#custom-id)` link in the .md file then pointed at nothing, and
// Lychee (which scans the .md exports) fell back to the heading-text slug and
// reported "Cannot find fragment" (kagent-dev/website#737).
//
// The partial now restores `{#custom-id}` when the id differs from the slug of
// the heading text, and leaves auto-id headings alone.

const IS_FIXTURE_TARGET = target.name.startsWith("docs-theme-extras-fixture");

const md = (rel: string) => readFixture(path.join(TEST_PRODUCT_ROOT, rel));

test.describe(".md export keeps explicit heading ids", () => {
test.skip(!IS_FIXTURE_TARGET, "fixture-only: relies on the extras fixture pages");

test("explicit id that differs from the slug is kept as {#id}", () => {
const out = md("v1/reference/cel/variables.md");
expect(out).toMatch(/^## Functions: policy\.all \{#functions-policy-all\}$/m);
});

test("auto-id heading gets no attribute", () => {
const out = md("v2/ol-split.md");
const line = out.split("\n").find((l) => /^## Shape 1\b/.test(l));
expect(line, "Shape 1 heading missing from ol-split.md").toBeTruthy();
expect(line).not.toContain("{#");
});

test("no placeholder leaks into the output", () => {
for (const rel of ["v1/reference/cel/variables.md", "v2/ol-split.md", "v2/everything.md"]) {
expect(md(rel), rel).not.toContain("XHEADINGIDPLACEHOLDER");
}
});
});
Loading