Skip to content

site: the sidebar lists the 1bit OS, install and client pages (22 -> 27 doc pages reachable) - #30

Merged
bong-water-water-bong merged 1 commit into
mainfrom
seo/sidebar-appliance
Nov 8, 2026
Merged

bong-water-water-bong merged 1 commit into
mainfrom
seo/sidebar-appliance

Conversation

@bong-water-water-bong

Copy link
Copy Markdown
Contributor

The docs sidebar could not reach the appliance's own pages. Measured on site bedd0c5 with the engine at main:

before after
doc pages 40 40
reachable from the sidebar 22 27
os-v3 (why the appliance is Puppy) not in NAV in NAV
install (how to get it) not in NAV in NAV
install-any-distro (the engine on an existing Linux) not in NAV in NAV
clients (what talks to it) not in NAV in NAV
os-v3-live-puppy-eval (why Puppy, measured) not in NAV in NAV

So "how do I run this" was reachable only from the docs index, llms.txt and 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 why install.html had zero impressions in Search Console: nothing but the index pointed at it.

What changes

  • A 1bit OS nav 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_META for 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 and llms.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's PAGE_META for os-v3/install/clients is carried here verbatim, so when #16 is rebased onto this it is release-post-only.

Verified at fcb33c9

Site render: 67 pages, rc 0 (the guard from #23 included). The 1bit OS group 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.

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.
@bong-water-water-bong

Copy link
Copy Markdown
Contributor Author

@pi-prs ready for review at fcb33c9. Site tools/site.py only: a new "1bit OS" sidebar group (os-v3, install, install-any-distro, clients, os-v3-live-puppy-eval) plus PAGE_META for the five, so doc pages reachable from the sidebar go 22 -> 27 of 40. This is the navigation half of #16 split out (its other half is the held release post); #16 PAGE_META carried verbatim. 67 pages rc 0, one

each, titles <=60, descriptions 148-157. Merging deploys the site, so timing is the owner call under the hold.

@bong-water-water-bong bong-water-water-bong left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 bong-water-water-bong left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

@bong-water-water-bong
bong-water-water-bong merged commit 8f01865 into main Nov 8, 2026
2 checks passed
bong-water-water-bong added a commit that referenced this pull request Nov 8, 2026
#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>.
bong-water-water-bong added a commit that referenced this pull request Nov 15, 2026
…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>
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.

1 participant