Restore topic-tree navigation for the 1.5/1.6 split - #167
Merged
Conversation
The Explorer builds the sidebar purely from folder structure, so moving the
31 forked pages into docs/1.5/ and docs/1.6/ punched holes in the topic tree.
Installation -> Server listed only Requirements, Virtualization and Uninstall;
"Install FOG Server" appeared nowhere under Installation. The same hole existed
for the DHCP pair, Plugins, LDAP, Site Scoping, the nine-page PKI/Secure Boot
reference set and 20 others. The two version pills were the only way in, which
requires the reader to already know that version matters for that topic.
Adds an unversioned chooser page at each of the 31 topic paths. Each states
what actually differs between the versions -- written per page from the 1.6
page's own callout and the 1.5 page's description, not templated -- and links
both. The nav entry comes back and the reader learns whether they need to care
before clicking.
The 1.6 page keeps the unsuffixed context_id, title and aliases, so every
/{context_id} permalink still resolves to the newest docs. Choosers take
<basename>-versions and declare no aliases, so they never compete for the
redirect stub. Each carries a version-chooser tag, which is the inventory the
teardown runbook works from.
Also repairs 209 dead links the original split left behind. Every unversioned
link to a forked page from inside a version tree pointed at a path with no page
on it -- management/server/install-fogsettings and friends were hard 404s,
including 15 pages linking their own headings. The build never warned. All 207
that needed it are now version-qualified; of the ~200 carrying an anchor,
check-anchors reports none broken.
The two 1.6-only pages move to the unversioned tree with an "applies to 1.6 and
later" callout, since there is nothing to choose between: certificates.md and
supported-customizations.md. Their old /1.6/... URLs are kept as aliases.
Two pre-existing bugs fixed in passing, both in files already touched here: an
unescaped pipe inside a wikilink in a table cell in supported-customizations.md
(it rendered literally), and 1.6/management/web/storage-node.md's description,
which was the home page's text copy-pasted.
Not changed: 116 qualified links on 28 unversioned pages. They resolve
correctly, and whether each one means "the topic" or "this version's page" is a
judgement per link -- a bulk rewrite would silently drop anchors.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Gxx8f94y8Ns8oyZmmnguHv
Reading order is encoded twice: in quartz.config.yaml's Explorer sortFn and in prev-next-nav's TOP_ORDER/EXPLICIT_ORDER. They cannot share a module -- the sortFn is a string inside YAML, shipped to the browser and rebuilt there with new Function -- so the duplication is structural and both must be edited together. prev-next-nav had already drifted since the split landed. Its EXPLICIT_ORDER still listed install-fog-server, command-line-options and migrating-fog-server under installation/server, pages that had moved into the version trees, and its TOP_ORDER knew nothing of 1.5 or 1.6. That is fixed here regardless of the chooser work. Both tables now carry the 31 choosers in reading order, and gain explicit orders for the five directories that needed one only once the choosers landed: installation/network-setup, kb/integrations, kb/reference, kb/troubleshooting, management/fos and management/server. management/web gains certificates and the nine choosers. The comments above each table said to keep them in sync with mkdocs.yml, which no longer exists. They now name each other, and point at VERSIONING.md for the check that compares them. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Gxx8f94y8Ns8oyZmmnguHv
Everything that can go wrong with the 1.5/1.6 split is silent. The Quartz build does not warn when a page vanishes from the nav, when a link inside a version tree resolves to a chooser and drops its anchor, or when the two nav-order tables disagree. Each produces a page that renders correctly and misdirects the reader. That is how the split removed "Install FOG Server" from the Installation nav and left 209 dead links without anything noticing. VERSIONING.md is the runbook: why a forked topic is three files and not two, which file owns which identifier and why that keeps permalinks on the newest docs, how to fork a page, the linking rules, and a 10-step teardown procedure for when 1.5 is deprecated. The teardown is cheap by construction -- the 1.6 pages already hold the final context_id, title and aliases, so they need no front-matter edit when they move up a level. CLAUDE.md carries the short version: the rules an agent must not break, and a pointer here. scripts/check-version-split.mjs enforces those invariants and needs no build: no unversioned links to forked pages inside the version trees, the two nav-order tables agreeing, every forked topic having a chooser, and no chooser claiming the newest version's context_id or any alias. Ten tests cover it, each pinning one failure shape rather than a green run, following the approach in check-anchors.test.mjs. scripts/show-nav.mjs prints the Explorer sidebar order from a terminal. The Explorer builds its tree client-side from contentIndex.json using the sortFn the config ships as a string, so nav order is not in the emitted HTML and cannot be grepped. This rebuilds the same trie and applies the real sortFn, so a page missing from the nav is catchable in CI rather than only by eye. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Gxx8f94y8Ns8oyZmmnguHv
Two conflicts, both from #168 forking Group Management while this branch was open. docs/management/web/index.md: master extended the "these differ between 1.5 and 1.6" callout to name Group Management and removed the plain groups entry from the list. This branch deletes that callout entirely, because the chooser pages replace it. Resolved to the list form, with Group Management marked as differing like its neighbours. Master's explanation of *what* differs is not lost -- it is now the body of the new groups chooser, which is where a reader looking at Groups will actually meet it. quartz/quartz.config.yaml: master added "groups" to the 1.5 and 1.6 management/web orders and dropped it from the unversioned one. This branch had rewritten the whole explicitOrder map. Resolved to this branch's map with master's "groups" folded into both version-tree orders, and kept in the unversioned order, since the chooser now lives there. Beyond the conflicts: - docs/management/web/groups.md is added as the 32nd chooser. #168 forked the topic correctly -- 1.6 keeps context_id "groups", 1.5 takes "groups-1.5" -- but the chooser convention did not exist when it was written, so Group Management had dropped out of the Management -> Web nav exactly as the other 31 had. This is the bug this branch exists to fix, so it is fixed here rather than left for a follow-up. - prev-next-nav's tables take the same "groups" edit, so the two stay in agreement. kb/reference/virus-scan-removed from #169 is 1.6-only and correctly needs no chooser; check-version-split.mjs reports it as such. Verified on the merged tree: build clean at 214 files, 61 tests pass, check-version-split reports 32 forked topics and no problems, check-anchors reports the same 3 pre-existing findings and no new ones, and /groups still redirects to the 1.6 page. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Gxx8f94y8Ns8oyZmmnguHv
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
1 participant
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.
Splitting FOG 1.5 and 1.6 into
docs/1.5/anddocs/1.6/(#160, #161) removed 31 pages from the topic nav. The Explorer builds the sidebar purely from folder structure, soInstallation → Serverended up listing only Requirements, Virtualization and Uninstall — "Install FOG Server" appeared nowhere under Installation. Same for the DHCP pair, Plugins, LDAP, Site Scoping, the nine-page PKI/Secure Boot reference set, and 20 more. The two version pills were the only way in, which requires the reader to already know that version matters for that topic.The fix
An unversioned chooser page at each of the 31 topic paths. Each says what actually differs between the versions, then links both:
The "what differs" paragraph is written per page from the 1.6 page's own
>[!info]callout and the 1.5 page'sdescription— not templated. It is the reason the page earns its place: a bare pair of links would add a click and tell the reader nothing.Verified with the new
scripts/show-nav.mjs:Permalinks are unaffected
The 1.6 page keeps the unsuffixed
context_id,titleandaliases, so/{context_id}still resolves to the newest docs. Choosers take<basename>-versionsand declare no aliases, so they never compete for the redirect stub. Checked against the build:/install-fog-server./1.6/installation/server/install-fog-server/plugins./1.6/management/web/plugins/pki-zones./1.6/kb/reference/pki-zones/install-fogsettings./1.6/management/server/install-fogsettingsThis is also what makes the eventual teardown cheap — when 1.5 is deprecated, the 1.6 pages move up a level needing no front-matter edit at all.
It also repairs 209 dead links
Worth reviewing on its own. Every unversioned link to a forked page from inside a version tree pointed at a path with no page on it.
management/server/install-fogsettingsand friends were hard 404s — including 15 pages linking their own headings. The build never warned. All 207 that needed it are now version-qualified; of the ~200 carrying an#anchor,check-anchors.mjsnow reports none broken.prev-next-navhad also drifted since the split: itsEXPLICIT_ORDERstill listed pages that had moved into the version trees, and itsTOP_ORDERknew nothing of 1.5/1.6. Fixed here regardless of the chooser work.Two 1.6-only pages moved
certificates.mdandsupported-customizations.mdhave no 1.5 counterpart, so there is nothing to choose between. They move to the unversioned tree with an "applies to FOG 1.6 and later" callout and get no chooser. Their old/1.6/…URLs are kept as aliases.Conventions and tooling
Everything that can go wrong here is silent — a page vanishing from the nav, a link resolving to a chooser and dropping its anchor, the two nav-order tables disagreeing. Each renders fine and misdirects the reader.
VERSIONING.md— why a forked topic is three files, who owns which identifier, how to fork a page, the linking rules, and a 10-step teardown runbook for deprecating 1.5.CLAUDE.md— the rules an agent must not break, pointing at the above.scripts/check-version-split.mjs— enforces the invariants, no build needed. 10 tests, each pinning one failure shape rather than a green run.scripts/show-nav.mjs— prints the Explorer sidebar order from a terminal. Nav order is built client-side fromcontentIndex.jsonand is not in the emitted HTML, so it could not be checked in CI before.Verification
npm run docs:build— clean, 210 files, exit 0node --test "scripts/*.test.mjs"— 61 pass, 0 failnode scripts/check-version-split.mjs— consistentnode scripts/check-anchors.mjs— 3 findings, all pre-existing and untouched (confirmed viagit diff): two MediaWiki-export leftovers (Knowledge_Base#Storage_Nodes,fog_on_a_mac#architecture) and1.5/…/hosts#MAC address, where the 1.5 page only has "Multiple MAC Address Support" — a content call, not a mechanical one.Deliberately not in scope
116 qualified links on 28 unversioned pages. They resolve correctly. Whether each means "the topic in general" (should point at the chooser) or "this version's page" (should stay qualified) is a judgement per link, and a bulk rewrite would silently drop anchors. Example:
kb/how-tos/lets-encrypt-setup.mdapplies to both versions but links the 1.6.fogsettingspage, so a 1.5 reader lands on the wrong page. Real, smaller than what this fixes, and pre-existing. Happy to do a per-link pass as a follow-up.Three other pre-existing literal wikilinks render as raw text (
[[Dashboard Error:,[[FOGUserGuide#…, and one indisplay-timezone.md) — also untouched.🤖 Generated with Claude Code
https://claude.ai/code/session_01Gxx8f94y8Ns8oyZmmnguHv