Repository navigation
site: the sidebar lists the 1bit OS, install and client pages (22 -> 27 doc pages reachable) - #30
Conversation
The docs sidebar had no way to reach the appliance's own pages. Measured on main (bedd0c5) with the engine at main: of 40 doc pages, 22 were in NAV, and the ones missing included os-v3 (why the appliance is Puppy), install (how to get it), install-any-distro (the engine on an existing Linux) and clients (what talks to it) - so "how do I run this" appeared only in the docs index and the sitemap, never in the sidebar every other page carries. Five entries in a new "1bit OS" group, with PAGE_META so they get a real title and description rather than the auto-derived first paragraph. Reachable from the sidebar: 22 -> 27 of 40. The remaining 13 are engineering notes (zero-copy, determinism, npu-plan, ...); they stay reachable from the docs index, the related-docs blocks and llms.txt, and adding them would make the sidebar a directory listing. This is the navigation half of #16 split out: #16 is the held release post and must not publish with the hold on, and the sidebar is not release text. #16's PAGE_META for os-v3/install/clients is carried here verbatim.
|
@pi-prs ready for review at each, titles <=60, descriptions 148-157. Merging deploys the site, so timing is the owner call under the hold. |
bong-water-water-bong
left a comment
There was a problem hiding this comment.
VERDICT: READY at fcb33c9a7840d189f48c9e387a62e68d37feaf94.
A sidebar gap with a measured before/after (22 → 27 of 40 doc pages reachable), and the pages it adds all exist in the engine tree, which is the only way this could be wrong:
docs/os-v3.md present docs/install.md present docs/install-any-distro.md present
docs/clients.md present docs/os-v3-live-puppy-eval.md present
The framing is right too: the sidebar could reach the engine's pages but not the appliance's own — why the appliance is Puppy, how to get it, what talks to it — which is exactly the set a reader arriving at the site needs first. +14 lines in tools/site.py, no page content touched, so indexing of the existing URLs is unaffected.
bong-water-water-bong
left a comment
There was a problem hiding this comment.
VERDICT: READY at fcb33c9a7840d189f48c9e387a62e68d37feaf94
Built the site twice — once at the merge base, once at this head — against the engine's current docs/ (40 pages, which is the denominator the PR quotes), and the nav delta is exactly what it claims:
base tools/site.py: 0 of the five new keys present
head tools/site.py: all five present
'os-v3' 'install' 'install-any-distro'
'clients' 'os-v3-live-puppy-eval'
ONEBIT_ENGINE_DIR=<engine main> python3 tools/site.py <out>
base: 67 pages head: 67 pages (no page count change: this is nav placement only)
and every one of the five resolves: docs/{os-v3,install,install-any-distro,clients,os-v3-live-puppy-eval}.md
exist on engine main, so none of the new sidebar links is a 404
So +5 entries, five real pages, no build breakage — and the reason in the comment is the accurate diagnosis: "They were reachable only through the docs index and the sitemap, which left 'how do I run this' off the sidebar of every other page (measured: 18 of 40 doc pages were not in NAV)." A page that is only in the sitemap is invisible to the reader who is already reading a page — that is a navigation defect, not an SEO one, and it is what this fixes.
One follow-up I found while building, for the engine repo rather than this PR: the build warns on one of the five,
os-v3-live-puppy-eval.md: 10 of 19 headings rendered — a bare closing html tag
(e.g. `</dev/null` in a table cell) deletes the rest of the page; write `< /dev/null`
so half that page is being swallowed by the markdown renderer at a </dev/null inside a table cell. It is pre-existing content (reachable via the sitemap today), but promoting it to the sidebar makes it more visible, and the fix is the one the warning names: write < /dev/null. Not a reason to hold this PR.
Not run: a browser check of the rendered sidebar (the build's output and the source delta are what I can take).
#30 merged the navigation half - the "1bit OS" sidebar group and PAGE_META for os-v3/install/install-any-distro/clients/os-v3-live-puppy-eval - so this branch's tools/site.py hunks are already on main and the PR had gone CONFLICTING/DIRTY against them. Rebuilt from origin/main (8f01865) with only this PR's own content: - blog/2026-11-02-the-first-release.md (new, draft: true - it does not render) - three dated "Update (2026-11-02)" notes on existing posts (every node on HRX, boot a stick, this week in the engine) saying the old "1bit OS live image" meant the BusyBox os/mini target and not the Puppy appliance Verified: 67 pages rc 0 and no the-first-release page in the build (draft, as intended); each touched post still renders one <h1>.
…t) (#16) #30 merged the navigation half - the "1bit OS" sidebar group and PAGE_META for os-v3/install/install-any-distro/clients/os-v3-live-puppy-eval - so this branch's tools/site.py hunks are already on main and the PR had gone CONFLICTING/DIRTY against them. Rebuilt from origin/main (8f01865) with only this PR's own content: - blog/2026-11-02-the-first-release.md (new, draft: true - it does not render) - three dated "Update (2026-11-02)" notes on existing posts (every node on HRX, boot a stick, this week in the engine) saying the old "1bit OS live image" meant the BusyBox os/mini target and not the Puppy appliance Verified: 67 pages rc 0 and no the-first-release page in the build (draft, as intended); each touched post still renders one <h1>. Co-authored-by: bong-water-water-bong <bong-water-water-bong@users.noreply.github.com>
The docs sidebar could not reach the appliance's own pages. Measured on site
bedd0c5with the engine atmain:os-v3(why the appliance is Puppy)install(how to get it)install-any-distro(the engine on an existing Linux)clients(what talks to it)os-v3-live-puppy-eval(why Puppy, measured)So "how do I run this" was reachable only from the docs index,
llms.txtand the sitemap — never from the sidebar that every other doc page carries. That is the internal-link half of the findability brief, and it is also whyinstall.htmlhad zero impressions in Search Console: nothing but the index pointed at it.What changes
1bit OSnav group with those five pages, labelled as tasks ("What it is", "Install 1bit OS", "The engine on any Linux", "Connect a client", "Why Puppy: the evaluation") rather than as filenames.PAGE_METAfor all five, so each gets a real search title and description instead of the auto-derived first paragraph — e.g.install.html's title becomes "Install 1bit OS: stick, internal disk, USB" (56 chars with the suffix), descriptions 148–157 (inside the build's 160 limit and the keyword map's 140–160 band).The other 13 doc pages still outside NAV are engineering notes (
zero-copy,determinism,npu-plan,lora,template-publishing, …). They stay reachable from the docs index, the related-docs blocks andllms.txt; adding them would make the sidebar a directory listing rather than a route through the product.Split from #16, deliberately
This is the navigation half of #16 (
docs: 1bit OS is the Puppy appliance; the held release post says so). #16 cannot merge while the owner's publishing hold is on, because its other half is the release post; the sidebar is not release text. #16'sPAGE_METAforos-v3/install/clientsis carried here verbatim, so when #16 is rebased onto this it is release-post-only.Verified at
fcb33c9Site render: 67 pages, rc 0 (the guard from #23 included). The
1bit OSgroup renders on doc pages, every target exists in_site, and the five pages each have exactly one<h1>, a title ≤60 with the suffix and a description inside 160. One file, +19/−1.Merge timing: this deploys the site when merged, so it is the owner's call under the hold — opening it now so it is ready.