Restore gallery captions and items the conversion flattened

[ptr727]

Closes#52.

What was wrong

A gallery is a flex row whose column widths come from .gallery-cols-N figure. Anything inside it that is not a figure gets no width from that rule and is laid out as one more item in the row. Three variants of that survived the WordPress conversion, and no gate could see any of them: every media check reasons about a URL, and content misplaced inside a gallery resolves and is linked exactly as correct content is.

Shape in the markdown	Count	What the old platform had
Caption text trailing the last figure shortcode's }}	11	<figcaption class="blocks-gallery-caption"> — a caption for the set
A bare  image	2	<li class="blocks-gallery-item"><figure>
A linked [](…) image	8	the same, with the <a>inside the figure

Why the capture was consulted rather than the markup

The first shape is why this is not a mechanical rewrite. Reading only the source, the obvious fix is to move the trailing text into that figure's caption parameter — which is what the review on #51 suggested, three times, and what #52 recorded as an open question.

The captured live site settles it: all eleven were blocks-gallery-caption elements, and the repo's eleven trailing texts match them exactly, one for one, with nothing on either side unaccounted for. They are captions for the set. Moving one into the last figure would have attributed a caption describing four images to whichever image sorted last, and it would have looked correct.

So the captions move to a caption on the gallery, and the container becomes a <figure>, because figcaption is only valid as a figure's child. The reset already sets figure { margin: 0 } and the theme already styles figure > figcaption, so a set caption needed exactly one rule of its own: a full-width flex basis, without which it packs onto the end of the last row and reads as a caption for whichever image it lands beside.

The other two shapes become figure shortcodes, the linked ones through the link parameter the theme already has, which puts the anchor back inside the figure where the original had it.

The gate

check-url-parity.py gains the check that would have caught all of this. It parses the built pages rather than matching text, because nested <figure> elements defeat a regex, and it fails on any direct child of a gallery that is not a figure or the gallery's own figcaption.

Demonstrated failing before being trusted. Against the pre-fix content it reports 27 stray nodes and exits 1. It distinguishes the shapes rather than counting them, naming bare text and each stray element type separately, so a future finding says what kind it is.

The gate found more than the review did. The linked-image variant is on moving-from-unraid-to-proxmox-ve, a post neither the Copilot review nor #52 mentions — it surfaced only by running the check across all 19 pages that carry a gallery. #52's own measurement of "12 across 2 pages" was low for the same reason: it looked for stray text, and eight of these are stray elements.

Verification

gallery: 19 pages with galleries, 0 stray nodes inside one
PASS - the built site honors the URL contract

Released through make-release.sh to the local mirror and checked against the running server: PASS - 1245 URLs honored, rules confirmed from the release just installed.

assets stays at 1049 and orphans stays at 98, both unmoved, which is the evidence that the rewrite lost no media and orphaned none. Build clean under hugo --gc --minify --panicOnWarning.

markdownlint-cli2 and editorconfig-checker clean on every file this touches. The MD012 warnings inside the edited post are pre-existing conversion artifacts, unchanged in count at 9 before and after, and content/** is excluded from the CI markdown glob by design.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Restores WordPress-conversion-flattened gallery structure (set-level captions and non-figure gallery items) and adds a gate to prevent future regressions by validating the built HTML structure of galleries.

Changes:

• Update the gallery shortcode to render as a <figure> with an optional gallery-level <figcaption>.
• Convert affected posts’ stray gallery children (trailing caption text, bare images, linked images) into proper gallery/figure shortcode structure.
• Extend check-url-parity.py with an HTML-structure check that flags any non-figure/figcaption direct children inside a gallery, plus supporting docs and CSS.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
layouts/shortcodes/gallery.html	Switch gallery wrapper to <figure> and add optional gallery-level caption rendering.
assets/css/extended/custom.css	Ensure gallery-level captions take full width in the flex layout.
checks/check-url-parity.py	Add gallery structure validation by parsing built HTML and reporting stray nodes.
checks/README.md	Document the new gallery structural check and the conversion artifact shapes it detects.
content/posts/2022/10/30/installing-flair-smart-vents-to-keep-room-temperatures-balanced.md	Move gallery captions from trailing text into gallery shortcode caption.
content/posts/2020/06/21/moving-from-unraid-to-proxmox-ve.md	Convert linked markdown images inside a gallery into figure shortcodes with link=.
content/posts/2020/02/02/recovering-the-firmware-on-a-supermicro-bpn-sas3-846el1-backplane.md	Convert bare markdown images inside a gallery into figure shortcodes.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.

Suppressed comments (1)

checks/check-url-parity.py:200

• The GalleryScan docstring says this logic catches “both conversion artifacts”, but checks/README.md (and the PR description) describe three distinct markdown shapes (trailing caption text, bare ![](...), and linked [![](...)](...)). Consider updating this docstring to match that 3-shape framing (or explicitly explain that the scanner sees two HTML-level shapes but they originate from three markdown patterns) so future readers aren’t confused about what the check is intended to detect.

 A gallery is a flex row of figures, so its column widths are set by `.gallery-cols-N figure`.
Anything else landing in there is not laid out by that rule and is rendered as one more item
in the row, which is how both conversion artifacts this catches presented: a set caption
written as trailing text after a figure shortcode became a bare text node, and a gallery item
the conversion emitted as a plain markdown image became a `<p>` wrapping two images.

[ptr727]

Answering the suppressed finding from the round on c97e7a8, which carried no thread to reply on.

The GalleryScan docstring says this logic catches "both conversion artifacts", but checks/README.md (and the PR description) describe three distinct markdown shapes

Correct, and it was stale rather than a different framing: I wrote that docstring when two shapes were known, and never revised it when the check itself found the third on a post neither the review nor #52 had mentioned.

Fixed in 76144bd, taking the second of the two options you offered rather than the first. Enumerating source patterns makes the docstring a list to extend every time the conversion surprises us again, and the surprise already happened once inside this branch. It now names the invariant instead — a gallery holds figures and its own caption — and says explicitly that the three markdown patterns arrive here as three different HTML shapes. That is what covers the shape nobody has thought of yet, which is precisely how the third one was found.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.

Suppressed comments (1)

checks/check-url-parity.py:243

• GalleryScan doesn’t implement HTMLParser.handle_startendtag, so XHTML-style void tags like <br/> or <img/> won’t be reported as stray direct children (and won’t participate in depth tracking). That can let a gallery-structure regression slip through if the HTML serializer emits self-closing void tags.

 def handle_starttag(self, tag, attrs):
classes = dict(attrs).get("class", "").split()
if self.depth is None:
if tag == "figure" and "gallery" in classes:
self.depth = 0

[ptr727]

Answering the suppressed finding from the round on 76144bd, which carried no thread.

GalleryScan doesn't implement HTMLParser.handle_startendtag, so XHTML-style void tags like <br/> or <img/> won't be reported as stray direct children

Refuted, by running it rather than reading it.HTMLParser.handle_startendtag is not abstract — its own implementation forwards to handle_starttag and then handle_endtag, so the self-closing spellings already arrive at the code that reports them:

Input inside a gallery	Reported
<br>	<br> as a direct child
<br/>	<br> as a direct child
<br />	<br> as a direct child
<img/>	<img> as a direct child
<figure/> then <p>after</p>	<p> as a direct child — the self-closing non-void case enters and exits correctly, so what follows it is still seen
a clean gallery	nothing

Adding the override is in fact what would break it: handle_startendtag firing and the base class's split would count the pair twice, desynchronizing the depth for every gallery after it — the same failure the VOID set exists to prevent.

The reasoning was sound and only the base class's behaviour was wrong, which is worth more than a reply nobody reading the file later will find, so a7c8e70 records it as a comment at the class: no handle_startendtag override, deliberately, and here is what happens if you add one.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.

Suppressed comments (1)

checks/check-url-parity.py:304

• The new gallery check returns a list of "stray nodes", but the shared failure summary prints FAIL gallery: N missing, which is misleading when this check fails (the items aren’t missing). Consider special-casing the summary noun for the gallery label so failures read correctly without changing other checks’ wording.

 ("media", check_media(public)),
("assets", check_assets(public, refs)),
("orphans", check_orphans(public, refs)),
("gallery", check_galleries(public)),
):

[ptr727]

Answering the suppressed finding from the round on a7c8e70, which carried no thread.

the shared failure summary prints FAIL gallery: N missing, which is misleading when this check fails (the items aren't missing)

Correct, and fixed in c8f177c. The noun was wrong in the way that matters: the findings are nodes that are present, which is the entire complaint about them, so the summary described the opposite of the defect.

Taking the special-case shape you suggested. Each label can name its own noun and the default stays missing, so the four older checks are byte-identical in output and a check added later reads the way they do unless it says otherwise.

Verified by forcing a failure rather than reading the format string:

FAIL gallery: 15 stray nodes

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.