Skip to content

Confirm the banner renders as a callout (spec 011, Task 3.5) - #75

Merged
iancooper merged 1 commit into
masterfrom
docs/spec-011-task-3.5
Aug 5, 2026
Merged

Confirm the banner renders as a callout (spec 011, Task 3.5)#75
iancooper merged 1 commit into
masterfrom
docs/spec-011-task-3.5

Conversation

@iancooper

Copy link
Copy Markdown
Member

Closes the last leftover from Spec 011's requirements Q1: does the page banner actually
render as a callout below the title, or does GitBook emit it literally?

It needed a published branch, and #74 supplied one by merging — so this was checked
against the live site rather than a preview revision. Documentation only; no page
under contents/ is touched.

What was checked

GitBook emits <h1></header>, then the banner as the first element of the content
body:

<blockquote class="… border-l-2 pl-6 py-3 border-tint …">
  <strong>Explanation</strong> · Applies to <strong>Brighter V10</strong> ·
  Prerequisites: <a href="…/guaranteed-at-least-once/rabbitmqconfiguration">RabbitMQ Configuration</a>

A real blockquote with a left border and padding — a callout below the title, which is
what the convention asks for. **Reference** becomes <strong>, the · separators
survive as U+00B7, and the Prerequisites link is a genuine anchor (fetched: 200).

12 pages sampled across the corpus, including all five that carry a Prerequisites
segment
. That half of the banner grammar had never appeared in a rendered page until
the Phase 6 splits created pages using it, so this is the first time it has been
checkable at all.

The check that would have proved nothing

The first attempt read the page through a Markdown-converting fetcher, which returned:

> **Explanation** · Applies to **Brighter V10** · Prerequisites: [RabbitMQ Configuration](…)

That is exactly what a correctly rendered blockquote converts back to — and equally
what an unrendered literal banner would look like. The two are indistinguishable
after conversion, and GitBook rendering such things literally is precisely the concern
behind Q1. The check had to be run against raw HTML for the <blockquote> element, and
was.

Also settled

The published site is 111 URLs (sitemap-pages.xml) — 110 pages plus the index — so
all five pages created by the Phase 6 splits are live, and none is orphaned in the
published tree.

Verification

python3 tools/linkcheck.py     # No broken internal links (112 files checked)
python3 tools/pagelint.py      # 0 errors, 836 warnings across 110 pages

Spec 011 is now 40 of 43 tasks. Remaining: the language-tag backfill, --fix for
pagelint.py, and the acceptance pass.

🤖 Generated with Claude Code

https://claude.ai/code/session_012tcdwxVb8NmKaX2S6fvyFg

The last leftover from requirements Q1, and it needed a published branch.
PR #74 merged first, so it was checked against the live site rather than
a preview.

GitBook emits <h1> ... </header>, then the banner as the first element of
the content body: <blockquote class="... border-l-2 pl-6 py-3 ...">. A
real blockquote with a left border and padding -- a callout below the
title, which is what the task asked. Inside it **Reference** becomes
<strong>, the " . " separators survive as U+00B7, and the Prerequisites
link is a real <a href> returning 200.

12 pages sampled across the corpus, including all five that carry a
Prerequisites segment. That segment had never appeared in a rendered page
until the Phase 6 splits created pages using it, so this is the first
time the optional half of the banner grammar has been checkable at all.

The obvious check would have proved nothing. Reading a page through a
Markdown-converting fetcher returns "> **Explanation** . Applies to ...",
which is exactly what a correctly rendered blockquote converts back to,
and equally what an unrendered literal banner would look like. The two
are indistinguishable after conversion -- and GitBook emitting front
matter and blockquotes literally was the concern behind Q1 in the first
place. The check had to be run against raw HTML for the <blockquote>
element, and was.

Also settled: the published site is 111 URLs (sitemap-pages.xml), being
110 pages plus the index, so all five split pages are live and none is
orphaned in the published tree.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012tcdwxVb8NmKaX2S6fvyFg
@iancooper
iancooper merged commit 61a83ed into master Aug 5, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant