Skip to content

📖✨:give the docs pages the site's design - #1846

Merged
openinf-commit-queue[bot] merged 1 commit into
livefrom
feat/docs-pages
Aug 24, 2026
Merged

openinf-commit-queue[bot] merged 1 commit into
livefrom
feat/docs-pages

Conversation

@DerekNonGeneric

@DerekNonGeneric DerekNonGeneric commented Aug 23, 2026 •

Copy link
Copy Markdown
Member

The index was rebuilt and the fourteen pages under it were not. Every link out
of it landed in a 48ch column wrapped in .grid, .unit, .four-fifths and
.improve, none of which are styled anywhere in the repository.

Following Google's developer documentation style guide in structure, since the
handbook content is already written in its markup, but in this site's own
palette and type rather than devsite's.

Fixes: #1545

Breadcrumbs

That issue asks for a solid breadcrumb, and points at
ampproject/amp.dev#3036, where the trail in one section never terminated
while another section's did. The difference is where the trail comes from.

Splitting a URL on slashes would link into nothing on thirteen of fifteen
deep pages here. There is no page at /docs/handbook/, at /docs/dev/faq/, or
at /news/2026/08/. So a step appears only where a page sits at that URL, or
where _data/sections.json names somewhere else it can point, and the trail
always terminates at the front page. Zero dead links across the site.

It stops short of the page it is on, whose title is the heading directly below
it and was otherwise read twice. The BreadcrumbList structured data still
carries the whole chain, because search results want it.

This is what deep-page.liquid was always for, and it has that back.

Four things now render that never have

The Key Point. Every handbook page carries one. Only the index read it.

The credit the colons page owes Google. It reproduces CC BY 4.0 content and
the only layout that ever rendered the credit is one no page loads.

Recommended against not recommended. The content has carried
.compare-better and .compare-worse all along, unstyled, so both halves were
the same plain text and a reader could not tell which example was the good one.

Callouts. > [!NOTE] was reaching the page as literal bracketed text.

Licensing

Each page states the terms of the license file beside it: CC BY-SA 4.0 under
handbook/, CC BY-NC-SA 4.0 elsewhere, with the Creative Commons buttons for
those terms rather than one fixed pair. A page adapted from Google says so with
google: true, which reads the source page off its own filename; where the two
differ, google: inclusive-documentation names Google's slug instead. Two
pages are credited, eleven are not.

Worth a look before merging: the deleted layout claimed CC BY 4.0 for OpenINF's
own content, contradicting both the README and the two LICENSE directories.
Two sources agree with each other and disagree with it, so this follows them.

Also

Pages date themselves from when git last touched them, so deploy.yml needs
fetch-depth: 0; a shallow clone would date every page to the build, and the
filter reports nothing rather than guess. "Improve this page" opens against
live rather than HEAD, which GitHub's editor cannot commit to.
handbook-content-g-devdocs-style.liquid and key-point.liquid are deleted.

Checks

nps test passes, all 17. Every internal link and asset reference in the built
site resolves, as does every anchor. One h1 a page, no skipped heading levels,
no dangling aria-labelledby, and fifteen valid BreadcrumbList blocks.

Contrast is computed against composited color, not read off the palette. Text
runs 5.34:1 to 13.97:1; the three rules that are not text sit at 3.37, 3.39 and
4.33 against the 3:1 they answer to.

The four page shapes were rendered at 1440, 1024, 820 and 390 and had no
horizontal overflow. That was before the breadcrumb, the buttons and the edit
control were added, and those have not been through a browser: each wraps or
is small enough not to set a floor, and the wide table is its own scroll
container, but the reasoning is structural rather than seen.

Two bugs came out of rendering rather than reading. Bootstrap's
--bs-code-color was turning every inline code span pink, and two autolinked
bare URLs overflowed at 390px.

@netlify

netlify Bot commented Aug 23, 2026 •

Copy link
Copy Markdown

✅ Deploy Preview for gh-pages-openinf ready!

Name Link
🔨 Latest commit 56ca587
🔍 Latest deploy log https://app.netlify.com/projects/gh-pages-openinf/deploys/6a8ba688843d0500081cb714
😎 Deploy Preview https://deploy-preview-1846--gh-pages-openinf.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@DerekNonGeneric
DerekNonGeneric force-pushed the feat/docs-pages branch 12 times, most recently from 4bef31e to 6550bfa Compare August 24, 2026 01:44
@socket-security

socket-security Bot commented Aug 24, 2026 •

Copy link
Copy Markdown

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff Package Supply Chain
Security
Vulnerability Quality Maintenance License
Addedmarkdown-it-github-alerts@​1.0.19910010080100

View full report

The index was rebuilt and the fourteen pages under it were not, so
every link out of it landed on a 48ch column wrapped in `.grid`,
`.unit`, `.four-fifths` and `.improve`, none of which are styled
anywhere.

Four things now render that never have. The Key Point each handbook
page carries, which only the index was reading. The attribution the
colons page owes Google, whose only renderer was a layout no page
loads. A trail back up, which the pages had no link for. And the
recommended and not-recommended examples as a distinguishable pair,
having until now been the same plain text twice.

The terms each page states come from the license files beside it:
CC BY-SA 4.0 under the handbook, CC BY-NC-SA 4.0 elsewhere. A page
adapted from Google says so with one line of frontmatter, which reads
the source page off its own filename.

The trail is built from somewhere a reader can go rather than from
the slashes in a URL. Nothing sits at `/docs/handbook/` or at
`/news/2026/08/`, so splitting the URL would link into nothing on
thirteen of fifteen pages; a step appears only where a page or a
named section does. That is what `deep-page` is for, and it has it
back.

Signed-off-by: Derek Lewis <DerekNonGeneric@inf.is>
Assisted-by: Claude-Code:claude-opus-5
Assisted-by: Claude-Code:claude-fable-5
Fixes: #1545
@OpenINFbot OpenINFbot added the 🚀 Status: Commit Queue Land this pull request when its checks pass label Aug 24, 2026
@openinf-commit-queue openinf-commit-queue Bot removed the 🚀 Status: Commit Queue Land this pull request when its checks pass label Aug 24, 2026
@openinf-commit-queue

Copy link
Copy Markdown

The commit queue did not land this. See https://github.com/OpenINF/openinf.github.io/actions/runs/32682535207 — the label has been taken back off, so re-applying it is a deliberate second try.

@OpenINFbot OpenINFbot added the 🚀 Status: Commit Queue Land this pull request when its checks pass label Aug 24, 2026
@openinf-commit-queue
openinf-commit-queue Bot merged commit c65d97f into live Aug 24, 2026
16 of 18 checks passed
@openinf-commit-queue openinf-commit-queue Bot removed the 🚀 Status: Commit Queue Land this pull request when its checks pass label Aug 24, 2026
@OpenINFbot
OpenINFbot deleted the feat/docs-pages branch August 24, 2026 02:26
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.

🧩✨ Eleventy breadcrumb plugin

2 participants