Move the local edits out of the vendored theme, and document its width knobs - #40
Merged
Merged
Conversation
The vendored PaperMod copy carried site customization in two of its files, which is what made an update a diff-and-reapply rather than a directory replace, and what put the repo in breach of its own CODESTYLE rule to override a theme template rather than edit the theme in place. Both sat in extension points the theme documents for the purpose, so both move without a fork. Hugo resolves a project's own trees ahead of the theme's: - The Lexend body rule and the gallery shortcode's layout rules move to assets/css/extended/custom.css. PaperMod's head partial globs css/extended/*.css across the union of both assets/ trees, so a project file is picked up by the same glob that finds the theme's empty placeholder. It is named custom.css rather than blank.css so it unions in alongside that placeholder instead of shadowing it. - The Google Fonts preconnect and stylesheet links move to layouts/_partials/extend_head.html, which overrides the theme's comment-only partial outright. themes/PaperMod/ is now byte identical to upstream 154d006e across all 125 files, verified by diffing against a clone at that commit. themes/README.md records the verification command so the claim stays checkable, and records why a submodule is the only fetch mechanism that would gain a bot here: PaperMod tags releases as v8.0, which is not valid semver, so Hugo Modules could only pin a pseudo-version and Dependabot does not upgrade those. The two root layouts/ overrides are untouched. They work around Hugo 0.158 deprecations upstream has not tracked, rather than customizing the site. Rendered output is byte identical to the previous build, hashed stylesheet name included. Verified under hugo --gc --minify --panicOnWarning, with the URL contract passing at 328/328, 778/778, and 1012/1012, and editorconfig-checker and markdownlint clean. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The question "how do I widen the page" has no answer in hugo.yaml, and finding that out costs a read of the theme's CSS. PaperMod exposes no width parameter to any template, so the only levers are four custom properties on :root in core/theme-vars.css, and nothing in the repo said so. themes/README.md gains a "Customization points" section recording the four variables, what consumes each and at what computed width, and two things that are easy to get wrong: - The width is a fixed pixel cap with no responsive term. zmedia.css, the theme's only media-query file, never touches --main-width or --nav-width, so the content column is 720px from a laptop to an ultrawide. The nav is already 304px wider than the content, so the two have to move together. - Overrides belong in assets/css/extended/custom.css, which the head partial concatenates after the core sheet, so they win on source order with no !important. The trap is that media queries add no specificity, so a top-level :root there also beats zmedia inside its own breakpoint. That is safe for the width variables, which zmedia never sets, and wrong for --gap, which it does. The section also records why the default stands: 720px at 18px is about 80 characters per line, already at the top of the readable range. Images and galleries inheriting the same cap is the part that costs something on a wide display, and the fix for that is media breaking out of the column rather than a wider column. TODO.md carries a one-line pointer under Open decisions so the question is findable from the place someone would look for it. OPERATIONS.md is deploy and serving, so it is the wrong home. Docs only. No rendered byte changes; verified under hugo --gc --minify --panicOnWarning against the same baseline, with markdownlint and editorconfig-checker clean. The audit report's themes/README.md:12 citation for hugo.vendored.provenance still lands on the commit row. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
This pull request relocates site-specific PaperMod customizations out of the vendored theme directory (so themes/PaperMod/ can be replaced wholesale on updates) and documents the theme’s width-related CSS customization points in themes/README.md.
Changes:
- Moved Lexend + gallery CSS into
assets/css/extended/custom.cssand moved the font<link>tags into a root-levellayouts/_partials/extend_head.htmloverride. - Removed the previously vendored modifications from
themes/PaperMod/to restore byte-identical parity with the recorded upstream commit. - Added documentation about PaperMod layout width “knobs” and recorded the update/verification workflow in
themes/README.md(+ a pointer inTODO.md).
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| TODO.md | Adds an “Open decisions” pointer to the new width/customization documentation. |
| themes/README.md | Documents vendoring provenance, confirms no local edits, and adds a “Customization points” section for width variables/override pitfalls. |
| themes/PaperMod/layouts/_partials/extend_head.html | Removes previously local font <link> tags from the vendored theme partial. |
| themes/PaperMod/assets/css/extended/blank.css | Removes previously local Lexend + gallery CSS from the vendored theme placeholder stylesheet. |
| layouts/_partials/extend_head.html | Adds project-level override to load the Lexend font links outside the vendored tree. |
| assets/css/extended/custom.css | Adds project-level CSS for Lexend body font styling and gallery layout rules outside the vendored tree. |
Two findings from the review of #40. The width table said `--nav-width` is consumed by `.nav`. It is not; the theme applies it to `.header-nav` in common/header.css, and `.nav` is not a selector in the theme at all, only `.nav-sep`. A reader following the table would have searched for a rule that does not exist. Both rows now name the file as well as the selector, since the point of the table is to be followed. `.gallery-cols-5 figure` really is wrong: the rule's own pattern is 1/N (100, 50, 33.33, 25, ..., 16.67) and the five-column case repeats the four-column 25%, so it renders four per row and wraps the fifth. It predates this branch, and one page uses it. It is recorded under Open decisions rather than fixed here, because this branch's claim is that the move changed no rendered byte and is verified by diffing the built site. A render change would retire the only evidence that the move was safe. It is a one-value fix worth its own change, where it can be looked at rather than diffed. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
ptr727
added a commit
that referenced
this pull request
Aug 7, 2026
The gallery column rules are 1/N widths: 100%, 50%, 33.3333333333%, 25%, 16.666666666%. The five-column case repeated the four-column 25% rather than 20%, which is the shape of a copied line, not a decision. It arrived with the original edit to the theme's extended/blank.css slot and moved verbatim in #40, which claimed to change no rendered byte and so could not correct it. The rendered effect today is none, and the raised finding overstated it. One page passes cols="5", and its gallery is empty: {{< gallery cols="5" >}} {{< /gallery >}} so it emits <div class="gallery gallery-cols-5"></div> with no figures inside, and no figure anywhere on the site is laid out by this rule. The five-per-row claim was not checked against the rendered page before it was repeated. This is therefore a latent fix: it is what the next cols="5" gallery will need, not a defect anyone can see now. The empty shortcode is a content artifact from the WordPress import and is left alone, since content/ is an imported archive that style sweeps do not reach. The rule-level diff of the emitted stylesheet is one line, 25% to 20%. Every built page still differs, because the stylesheet is fingerprinted and each page carries its hash and integrity attribute; per page that link is the only change. URL contract passes 328/328, 778/778, 1012/1012. themes/PaperMod/ is still byte identical to upstream 154d006e. TODO.md loses the Open decisions entry that recorded this, since it is done. Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
This was referenced Aug 7, 2026
ptr727
added a commit
that referenced
this pull request
Aug 7, 2026
#45) * Record the hub's verification ruling and what it will ask of this repo A finding that lives only in a chat message is not recorded. #597 was filed from here and its ruling landed, and neither appeared in this repo's own backlog, so the next session would have re-derived the whole thing from the miss that started it. #597 is added to the open-against-the-hub table. It was filed after a mandatory pre-merge gate in OPERATIONS.md was skipped on #40, and the ruling is that a verification a runner cannot perform needs a declared destination rather than a better per-repository pointer, because the pointer is what failed. What #598 will ask of this repo is recorded with it, and so is the reason not to act yet: it is merged to the hub's develop and not to main, so it binds nothing, which is the trap this file already records about reading main as ground truth. The work itself is smaller than it sounds and is written down so it is not re-measured. This repo's OPERATIONS.md carries 13 level-two headings and matches none of the five declared today, so the change is a rename and reorder rather than new prose. Both gaps are near-misses rather than absences: the gate's own section is `Local Verification Before a Pull Request` against the incoming `Local Verification`, and `Backup and Restore` is one word from the declared `Backup and Recovery`. That shape is worth stating, since a repository that wrote its operational document before the spec declared headings will have covered the same ground under its own names. The absence of any signal is recorded too. OPERATIONS.md is presence-checked only, which is why the full audit on 2026-08-05 reported nothing about a file using none of the declared headings, and the heading check belongs to a hub cluster that has not shipped. Until it does, nothing here will fail. Reference definitions added for #597, #598, and this repo's #40. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * Correct the lead sentence the third hub finding invalidated Adding #597 to the table left the sentence above it saying "Two findings are open at the hub. Neither is work this repo can do." Both halves became false in the same edit: there are three, and the new one is the only entry in the table that this repo will act on. The second half was the more misleading of the two. A reader scanning for what this repo owes would have been told by the lead sentence that nothing in the table qualifies, and stopped there, which is the opposite of why the row was added. The sentence now separates the two kinds rather than generalizing over them, and points at the paragraph stating what the actionable one will ask. Verified by counting: three table rows, and a lead sentence that says three. #597 confirmed still OPEN at the hub rather than assumed, since the change answering it has already merged there and a closed issue would have made "open at the hub" wrong too. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What and why
themes/PaperMod/carried site customization in two of its own files. That is what made an update a diff-and-reapply rather than a directory replace, and it put the repo in breach of its ownCODESTYLE.mdrule to override a theme template rather than edit the theme in place.themes/README.mdalready identified the fix and deferred it to "the next update"; doing it now is what makes that next update cheap rather than what waits for it.Both edits sat in extension points the theme documents for the purpose, so both move without a fork. Hugo resolves a project's own trees ahead of the theme's.
gallery/gallery-cols-*rulesassets/css/extended/custom.cssextended/blank.cssslotlayouts/_partials/extend_head.htmlextend_head.htmlpartialThe CSS file is named
custom.cssrather thanblank.cssso it unions in alongside the theme's placeholder instead of shadowing it. The theme's head partial globscss/extended/*.cssacross the union of bothassets/trees, so a project file is picked up by the same glob.themes/PaperMod/is now byte identical to upstream154d006eacross all 125 files. Verified by diffing against a clone at that commit;themes/README.mdrecords the command so the claim stays checkable rather than asserted.The two root
layouts/overrides are untouched. They work around Hugo 0.158 deprecations upstream has not tracked, rather than customizing the site, which is why they are not in the table.Second commit: the width knobs
"How do I widen the page" has no answer in
hugo.yaml— PaperMod exposes no width parameter to any template — and finding that out costs a read of the theme's CSS.themes/README.mdgains a Customization points section recording the four:rootvariables, what consumes each and at what computed width, and two things that are easy to get wrong:zmedia.css, the theme's only media-query file, never touches--main-widthor--nav-width, so the content column is 720px from a laptop to an ultrawide. The nav is already 304px wider than the content, so the two have to move together.assets/css/extended/custom.css, concatenated after the core sheet, so they win on source order with no!important. The trap: media queries add no specificity, so a top-level:rootthere also beatszmedia.cssinside its own breakpoint. Safe for the width variables, which zmedia never sets; wrong for--gap, which it does.The default stands deliberately — 720px at 18px is about 80 characters per line, already at the top of the readable range.
TODO.mdcarries a one-line pointer under Open decisions.OPERATIONS.mdis deploy and serving, so it was the wrong home.Verification
Local Hugo is
v0.164.0 extended, the exact version.github/actions/install-hugo/action.ymlpins and SHA256-verifies, so this is the same build CI runs.diff -rof the built site, which CI does not do.hugo --gc --minify --panicOnWarning.markdownlint0 issues;editorconfig-checkerclean.README.md+HISTORY.md, neither touched. No workflow, shell, or config files changed.themes/README.md:12citation forhugo.vendored.provenancestill lands on the commit row.Not in scope
Switching to a submodule or Hugo Modules. Recorded in
themes/README.mdfor the next reader: a submodule is the only fetch mechanism that would gain a bot here, because PaperMod tags releases asv8.0, which is not valid semver, so Hugo Modules could only pin a pseudo-version and Dependabot does not upgrade those. Weighed against what a bot would have found — upstream's only commit between 2026-05-10 and 2026-08-06 edited its own README. This PR is the precondition either way.🤖 Generated with Claude Code