Skip to content

📖✨:give the docs an index - #1841

Merged
openinf-commit-queue[bot] merged 2 commits into
livefrom
chore/docs-index
Aug 21, 2026
Merged

📖✨:give the docs an index#1841
openinf-commit-queue[bot] merged 2 commits into
livefrom
chore/docs-index

Conversation

@DerekNonGeneric

Copy link
Copy Markdown
Member

/docs/ was five paragraphs of Latin, and the home page links to it. It was
never missing documentation — thirteen real pages already published underneath
it. What was missing was the index that lists them.

The handbook already had its index copy

Every handbook page carries a key_point in its frontmatter: one sentence
stating the rule it makes. A colon indicates that closely-related information
follows.
Nine of them, written and invisible — the include that renders them,
_includes/key-point.liquid, is only called from
_layouts/handbook-content-g-devdocs-style.liquid, which no page uses. There
is no devsite markup anywhere in _site/.

So the index puts each rule beside its name. Most lookups end on this page
rather than one page in.

It says what it does not have

Five of the nine handbook pages are placeholders that read "Yet to be written."
They now carry stub: true, and the index reports 4 of 9 written and marks
each one. On a community site a named gap is a job somebody can pick up, and
each of these is small and self-contained.

The count, the flags, and the invitation in the header all read from the same
collection the list is built from, so they cannot drift apart from it.

Nothing here is typed

Two collections in eleventy.config.mjs. A doc appears on the index by
existing. The handbook sorts alphabetically, because reference is consulted by
looking things up; the community docs sort by an order they set, and a doc
without one stays off until somebody places it.

The four docs mirrored from OpenINF/.github keep their summaries in
siteify-health-files.mts beside their titles, so regenerating them does not
drop the text.

Two fixes alongside

The Edit link on every page under /docs/ pointed at
github.com/OpenINF/open.inf.is, which does not exist — the same dead name
behind the README links fixed earlier. Thirteen pages.

head.liquid now prefers a page's own description, which the whole site had
been filling with one site-wide sentence.

Checks

nps test passes, all 17. The page validates. Twelve foreground/background
pairs were computed against the true composited colour, translucent overlays
included, and every one clears AA; most clear AAA. Rendered at 1440, 1024, 820,
and 390, with no horizontal overflow at any of them, and the navbar's own focus
ring confirmed untouched.

Noted, not fixed

.tag-soon on the home page sets $body-bg text on solid $quaternary:
4.33:1 at 11px, under the 4.5:1 floor. It is pre-existing and out of scope
here. This page needed the same "not yet" hue and uses a pale wash with
deep-shade text instead, at 6.91:1.

_home.scss and _docs.scss now both define .wrap and a scoped main
reset. _home.scss:71 predicted this. Lifting the shell into a shared partial
belongs with the stylesheet-seam work rather than here, so this file reads the
Sass variables directly instead of copying the home page's token block.

@netlify

netlify Bot commented Aug 21, 2026

Copy link
Copy Markdown

Deploy Preview for gh-pages-openinf ready!

Name Link
🔨 Latest commit a10c29c
🔍 Latest deploy log https://app.netlify.com/projects/gh-pages-openinf/deploys/6a87c85743cea100086f8468
😎 Deploy Preview https://deploy-preview-1841--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 chore/docs-index branch 3 times, most recently from 1afb9d1 to d4c277a Compare August 21, 2026 03:31
The page at /docs/ was five paragraphs of Latin, and the home page
links to it. Thirteen real pages already published underneath it,
reachable only by knowing the URL.

Every handbook page carries a `key_point`: one sentence stating the
rule it makes. Nothing rendered it. The include that would have,
`key-point.liquid`, is called from a layout no page uses. So the index
puts each rule beside its name and most lookups end here rather than a
page in.

Five of the nine handbook pages are placeholders. The index says which,
and how many, because on a community site a gap that is named is a job
somebody can pick up. The count and the flags are read from the same
collection the list is built from, so they cannot disagree with it.

Both groups come from collections rather than a typed list. A doc
appears by existing, and the four mirrored from OpenINF/.github carry
their summaries in the task that generates them, so a regeneration does
not drop them.

The Edit link on every page under /docs/ pointed at OpenINF/open.inf.is,
which does not exist. Pages can now also set their own `description`,
which the whole site had been filling with one site-wide sentence.

Signed-off-by: Derek Lewis <DerekNonGeneric@inf.is>
Assisted-by: Claude-Code:claude-opus-5
Assisted-by: Claude-Code:claude-fable-5
The masthead's own rules had the right colours all along: parchment for
the GitHub row, parchment at 82% for the line about the Code of Conduct.
Neither reached the page. `.home main a` is (0,1,2) and carries the deep
teal meant for links on parchment; a rule naming only the row it styles
is (0,1,1) and loses to it. On the ink that teal reads 2.62:1, the same
number and the same cause as the navbar links.

The band now sets a legible colour for any link inside it, and the rules
that differ from it carry `main` too, so a link added to the masthead
later starts readable rather than starting at 2.62:1.

The docs page had it in `.invite`, where the link now takes the mono and
the parchment `.join-row` gives the home page's equivalent link, both
boxes being the same box. 13.97:1, 9.72:1, and 12.78:1.

Signed-off-by: Derek Lewis <DerekNonGeneric@inf.is>
Assisted-by: Claude-Code:claude-opus-5
@OpenINFbot OpenINFbot added the commit-queue Land this pull request when its checks pass label Aug 21, 2026
@openinf-commit-queue
openinf-commit-queue Bot merged commit 71c9909 into live Aug 21, 2026
15 checks passed
@openinf-commit-queue openinf-commit-queue Bot removed the commit-queue Land this pull request when its checks pass label Aug 21, 2026
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.

2 participants