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 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(