diff --git a/CHANGELOG.md b/CHANGELOG.md index bd0db78..2552791 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 `` 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`) diff --git a/layouts/_partials/page-to-markdown.html b/layouts/_partials/page-to-markdown.html index e57452f..99230c0 100644 --- a/layouts/_partials/page-to-markdown.html +++ b/layouts/_partials/page-to-markdown.html @@ -76,6 +76,29 @@ partial for the rationale. */ -}} {{- $html = $html | replaceRE `(?s)]*data-alert-copyas="([^"]*)"[^>]*>\s*]*hx:font-medium[^>]*>.*?

\s*]*>\s*]*>(.*?)\s*\s*\s*` "

[!$1]

$2
" -}} +{{- /* Explicit heading ids. Hextra puts the id on a 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)]*>.*?` $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 `()$` (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 @@ -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 `[“”]` `"` -}} diff --git a/playwright.config.ts b/playwright.config.ts index ac8388a..92f5786 100644 --- a/playwright.config.ts +++ b/playwright.config.ts @@ -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 diff --git a/tests/md-heading-ids.spec.ts b/tests/md-heading-ids.spec.ts new file mode 100644 index 0000000..b68dba5 --- /dev/null +++ b/tests/md-heading-ids.spec.ts @@ -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 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"); + } + }); +});