Skip to content

docs: fix first heading rendering as paragraph on two template guides#69890

Merged
pkozlowski-opensource merged 2 commits into
angular:mainfrom
erkamyaman:docs-fix-guide-h1-bom
Jul 22, 2026
Merged

docs: fix first heading rendering as paragraph on two template guides#69890
pkozlowski-opensource merged 2 commits into
angular:mainfrom
erkamyaman:docs-fix-guide-h1-bom

Conversation

@erkamyaman

Copy link
Copy Markdown
Contributor

The ng-container and binding template guide files each began with a
UTF-8 BOM (EF BB BF) before the leading `#`. The docs markdown parser
only promotes `#` to an H1 when it is the first character on the line,
so the BOM demoted the title to paragraph text (`<p># ...</p>`) and the
standard docs header (breadcrumbs, page title, edit button) never
rendered.

Stripping the BOM restores `#` as the first character, so both pages
now generate the proper `<header class="docs-header">` block. Verified
by rebuilding //adev/src/content/guide/templates:templates and
inspecting the generated HTML.

Fixes angular#69889
@pullapprove
pullapprove Bot requested a review from JeanMeche July 22, 2026 11:37
@angular-robot angular-robot Bot added the area: docs Related to the documentation label Jul 22, 2026
@ngbot ngbot Bot added this to the Backlog milestone Jul 22, 2026
@JeanMeche

JeanMeche commented Jul 22, 2026

Copy link
Copy Markdown
Member

Can we please add a compile time check for those characters ?

@github-actions

github-actions Bot commented Jul 22, 2026

Copy link
Copy Markdown

Deployed adev-preview for 0748605 to: https://ng-dev-previews-fw--pr-angular-angular-69890-adev-prev-mh4gn84y.web.app

Note: As new commits are pushed to this pull request, this link is updated after the preview is rebuilt.

…h 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 angular#69889 from recurring.
@angular-robot angular-robot Bot added the area: docs-infra Angular.dev application and infrastructure label Jul 22, 2026
@erkamyaman

Copy link
Copy Markdown
Contributor Author

Can we please add a compile time check for those characters ?

Done! I'm quite happy that I can finally use this meme!

columnnamefromhell-v0-uv5zct8pstcc1

@JeanMeche JeanMeche added action: merge The PR is ready for merge by the caretaker target: patch This PR is targeted for the next patch release labels Jul 22, 2026
@pkozlowski-opensource
pkozlowski-opensource merged commit ab52df4 into angular:main Jul 22, 2026
29 checks passed
@pkozlowski-opensource

Copy link
Copy Markdown
Member

This PR was merged into the repository. The changes were merged into the following branches:

@erkamyaman
erkamyaman deleted the docs-fix-guide-h1-bom branch July 22, 2026 12:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

action: merge The PR is ready for merge by the caretaker adev: preview area: docs Related to the documentation area: docs-infra Angular.dev application and infrastructure target: patch This PR is targeted for the next patch release

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Guide page renders the first H1 as a paragraph instead of the standard documentation header

3 participants