From bb670ce9dfd8096c3af0287e5f26190c88d54e39 Mon Sep 17 00:00:00 2001 From: Derek Lewis Date: Mon, 19 Oct 2026 07:43:16 +0000 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=96=F0=9F=94=A7=EF=BC=9Adrop=20the=20b?= =?UTF-8?q?ackslashes=20from=20generic=20API=20titles?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit TypeDoc escapes Markdown punctuation in its page headings, so the seventeen generic API pages took titles such as `Guard\` and showed the backslashes in their h1 and . The <title> was also printed unescaped, and the minifier read `<T>` there as a tag, which left a stray </T> in every such page's tab title. Unescape CommonMark backslash escapes when reading the title, and escape the <title> with escape_once so hand-written titles that already carry an entity render as before. A generic type is now covered by the stripTypeDocChrome tests. Signed-off-by: Derek Lewis <DerekNonGeneric@inf.is> Assisted-by: Claude-Code:claude-opus-5 --- _includes/head.liquid | 7 ++++++- build/shared/sdk-docs.mts | 4 +++- build/shared/sdk-docs.test.mts | 12 ++++++++++++ 3 files changed, 21 insertions(+), 2 deletions(-) diff --git a/_includes/head.liquid b/_includes/head.liquid index 37c718bff..67af54b09 100644 --- a/_includes/head.liquid +++ b/_includes/head.liquid @@ -18,7 +18,12 @@ {% if page.url == '/' -%} {{- siteTitle -}} {%- else -%} - {{- title }} · {{ siteTitle -}} + {%- comment -%} + Once, not plain escape: a hand-written title may already carry an + entity, while an SDK API title such as Guard<T> is plain text that + the minifier would otherwise read as a tag. + {%- endcomment -%} + {{- title | escape_once }} · {{ siteTitle -}} {%- endif %} {% if env == 'production' -%} diff --git a/build/shared/sdk-docs.mts b/build/shared/sdk-docs.mts index 254b3a04c..1a64c4da4 100644 --- a/build/shared/sdk-docs.mts +++ b/build/shared/sdk-docs.mts @@ -91,7 +91,9 @@ export function stripTypeDocChrome(markdown: string) { if (heading !== null) { return { - title: heading[1], + // TypeDoc escapes a heading's Markdown punctuation, as in `Guard\`, + // but the title is printed as plain text, where a backslash would show. + title: heading[1].replace(/\\([!-/:-@[-`{-~])/g, '$1'), content: content.slice(heading[0].length), }; } diff --git a/build/shared/sdk-docs.test.mts b/build/shared/sdk-docs.test.mts index 2e2904b0c..57b6cf8b5 100644 --- a/build/shared/sdk-docs.test.mts +++ b/build/shared/sdk-docs.test.mts @@ -79,6 +79,18 @@ describe('stripTypeDocChrome', () => { ); }); + test('unescapes the Markdown punctuation in a generic type’s title', () => { + deepStrictEqual( + stripTypeDocChrome( + '[**OpenINF**](../../README.md)\n\n***\n\n[OpenINF](../../packages.md) / [@openinf/util-types](../README.md) / Guard\n\n# Type Alias: Guard\\\n\n> **Guard**\\<`T`\\> = (`value`) => `value is T`\n' + ), + { + title: 'Type Alias: Guard', + content: '> **Guard**\\<`T`\\> = (`value`) => `value is T`\n', + } + ); + }); + test('handles a package readme with an HTML h1', () => { deepStrictEqual( stripTypeDocChrome(