From ab52df470a3be72d5d08d88af0c026cbf2ce8ee3 Mon Sep 17 00:00:00 2001 From: Kam Date: Wed, 22 Jul 2026 14:49:28 +0300 Subject: [PATCH] fix(docs-infra): fail the guide build when a markdown file starts with a BOM A leading UTF-8 byte order mark (U+FEFF) before the first `#` stops the Markdown parser from recognizing the heading, so the guide renders its title as a paragraph and drops the standard docs header. The character is invisible, so it cannot be caught in review. Add a check in the guides generation pipeline that throws when a source file starts with a BOM, failing the build with the offending file name. This sits alongside the existing unknown-anchor check and prevents the regression fixed in #69889 from recurring. --- adev/shared-docs/pipeline/guides/index.mts | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/adev/shared-docs/pipeline/guides/index.mts b/adev/shared-docs/pipeline/guides/index.mts index 89bcf9c9972..e0a315f592f 100644 --- a/adev/shared-docs/pipeline/guides/index.mts +++ b/adev/shared-docs/pipeline/guides/index.mts @@ -55,6 +55,16 @@ async function main() { } const markdownContent = await readFile(filePath, {encoding: 'utf8'}); + + // A leading byte order mark (U+FEFF) stops the first Markdown heading from being + // recognized, so the page title renders as a paragraph and loses its header. Fail + // the build so the BOM has to be removed from the source file instead. + if (markdownContent.charCodeAt(0) === 0xfeff) { + throw new Error( + `The file "${filePath}" starts with a byte order mark (BOM). Remove it so the leading heading is parsed correctly.`, + ); + } + const htmlOutputContent = await parseMarkdownAsync(markdownContent, { markdownFilePath: filePath, apiEntries: mapManifestToEntries(apiManifest),