Developer doc banners (#375)¶
Generated by test/visual/doc-banner-evidence.mjs.
What is being shown¶
There is no screenshot in this bundle, and that is the finding. The change removes bytes that were never painted, so a pixel diff would show two identical images and prove nothing. What needs proving is the opposite claim — that 19.9 MB left the wire and nothing else moved — and that is a measurement, not a picture.
How this bundle was produced¶
Two full Jekyll builds, served-byte measured:
- before —
origin/main@11c8b40,jekyll build --safe --strict_front_matter - after — this branch, same command
Measured¶
| before | after | |
|---|---|---|
| delivered HTML, 415 pages | 91,464,620 B | 71,603,991 B |
| comment payload | 19,877,745 B | 46,277 B |
| comment blocks | 142,840 | 1,405 |
| comment bytes per page | 47,898 B | 111 B |
| comment blocks per page | 344 | 3 |
21.7% of the delivered HTML was developer commentary. The 1,405 blocks that remain are the four Google vendor-snippet markers, plus comments in page content (which this change does not touch).
Why the per-page number is so much larger than the source diff¶
The source only loses 124,983 bytes of banner text. The delivered pages lose 47,898 bytes each, because an include's banner is re-emitted at every call site:
| page | comment bytes before | why |
|---|---|---|
authors/default/ |
130,840 B | post-card.html rendered 1,100 times, banner and all |
docs/ |
107,680 B | 1,709 comment blocks from repeated components |
A banner in a leaf component is not paid once. It is paid once per render.
Content equality — the actual safety claim¶
All 415 pages were compared after stripping comments and masking values that differ between any two builds minutes apart (?v=<epoch> cache-busters, ISO timestamps, data-date, the build stamp). 405 of 415 are byte-identical. The 10 that are not fall into two groups, both benign, both listed in metrics.json:
7 pages — reading-time estimate changed. The reading-time filter counts words in the rendered page, so it was counting developer banners. docs/ went from a claimed 63 minutes to 24. The old number was wrong; the new one is right.
3 pages — pre-existing Liquid leaks now emit less. These pages execute Liquid that should have been {% raw %}-protected, so theme output was already leaking into their body text. This change makes the leak smaller; it does not cause it:
CHANGELOG.md:311—`{% include core/head.html %}`in prose. Backticks do not protect from Liquid, which runs before Markdown, so the whole head include — stylesheets, meta tags, and Google Tag Manager — is injected a second time into the page body.pages/_docs/customization/layouts.md:81—{{ content }}inside an unprotected code fence, which dumped 74 KB of rendered layout output into what is supposed to be a five-line code sample.
Both are filed separately. Line 617 of the same CHANGELOG already uses the correct {% raw %} idiom, so the fix is a known one.
The regression guards — two tiers, on purpose¶
Source tier. test_developer_doc_banners_are_liquid in test/test_core.sh fails if any HTML comment reappears in _includes/** or _layouts/**. Verified in both directions: exit 0 on this branch, exit 1 on origin/main listing 1,065 offenders.
Served tier. test/visual/core/comment-payload.spec.js measures what a visitor actually receives — a 4,096-byte per-page comment budget, plus a check for doc-banner text (Path: _includes/, Template Logic:, a rule of =) in the delivered bytes. The source grep cannot see a banner that reaches the page some other way; this can.
Its last test is the one worth keeping. It divides comment payload by the number of rendered cards on /authors/default/, so a banner reintroduced inside a repeated component fails even if the per-page budget on some shorter page would have absorbed it. That is the exact shape of the original defect.
Both directions, measured:
/ |
/docs/ |
/404.html |
/about/ |
|
|---|---|---|---|---|
| before | 46,997 B / 310 blocks | 106,418 B / 1,707 | 43,697 B / 286 | 51,880 B / 350 |
| after | under budget | under budget | under budget | under budget |
9 passed against the fixed build; 9 failed against the pre-fix build.
It deliberately allows two things, so it can stay strict about everything else: comments inside <script>/<style>/<pre>/<textarea>/{% raw %} (those are JS, CSS, or sample markup shown on purpose), and the four exact boundary markers inside Google's own copy-paste snippets, kept verbatim so those blocks stay diffable against upstream. The exact-match is the point — prose that merely mentions GTM is a developer note like any other, and an early substring version of this rule wrongly spared three of them.
Comments are blanked out before the guarded spans are located. Without that, nanobar.html's banner — which contains the words <style> in a sentence — opened a span that hid the real comment below it.