docs(documentation): add page navigation and markdown rendering rules (v3.29.3) - #74
Merged
Conversation
…ules v3.29.2 named every page and stopped there. A reader landing on `how-to/HT-02-export-data.md` from a search or a pasted path had no way back to the index and no way on to `HT-03`, and the numbering that encodes reading order was visible only by listing the directory. New Phase 4 adds a breadcrumb under the H1, a prev/next footer on every subfolder page, and an H1 that repeats the file ID. Chains run within a subfolder — that is where the contiguous numbering lives — so prev/next point at siblings and need no `../`. Root pages are unnumbered, join no chain, and take the breadcrumb alone. Its second half is Markdown that renders as it reads: a single newline is not a line break, blank lines go around every list/table/fence/quote/heading, a nested fence inside a numbered step needs 3 spaces or the list restarts at 1, and paragraphs are not hard-wrapped. The Phase 5 procedure template now applies that to itself — When/Prerequisites/Time were stacked bold labels, now a bullet list. Both halves are salvaged from `docs/guide-file-naming-and-nav` (90ed1b7), whose naming scheme lost to v3.29.2 but whose page furniture was orthogonal to that disagreement. Rebased onto the released scheme rather than merged: the branch chained per audience prefix across directories, this chains per subfolder. Phases renumbered 4 -> 5 and 5 -> 6; Output now cites Phases 3-4. Bumps `ceh-documentation` 1.1.5 -> 1.1.6. DECISION_LOG entry 75 records the rebase. Generated with [Claude Code](https://claude.com/claude-code) by CEH
Ships page furniture for the guides `user-operator-guide` produces: an index breadcrumb and prev/next footer on every subfolder page, an H1 that repeats the file ID, and the Markdown line-break rules that keep a rendered page looking like its source. - Bump: PATCH — content-only addition to an existing skill, no new skill or agent - Manifests: ceh-documentation 1.1.5 -> 1.1.6 (plugin.json + marketplace.json) - Docs: CHANGELOG 3.29.3 added; ceh-documentation README gains a What It Produces bullet; root README needs no update (its row describes triggers, not output); CLAUDE.md unchanged — no project fact or structure moved Generated with [Claude Code](https://claude.com/claude-code) by CEH
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
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.
What
Adds Phase 4 — Page furniture and markdown that renders to
ceh-documentation:user-operator-guide, and releases it as v3.29.3.# HT-02 — Reset a password), so a printed or pasted page stillsays where it came from.
index.mdis the hub: no footer, lists every page grouped by subfolder inNNorder.3-space continuation indent inside numbered steps, no fixed-column hard wrapping.
Why
v3.29.2 gave every page a filename and nothing else. A reader landing on
how-to/HT-02-export-data.mdfrom a search or a pasted path had no way back to the index and no wayon to
HT-03— the numbering that encodes reading order was visible only to whoever listed thedirectory.
The second half exists because a guide that is correct in source and broken in a renderer is broken.
A single newline collapsing two lines into one paragraph is the most common way that happens.
How
Both halves are salvaged from
docs/guide-file-naming-and-nav(90ed1b7, 2026-07-31) — a branchthat solved the v3.29.2 naming problem differently (prefix by audience,
HT/OPonly, numberingglobal per prefix across the tree) and was superseded. Its page-furniture content was orthogonal to
that disagreement, so it was rebased onto the released scheme rather than merged:
../. Only the breadcrumb climbs.breadcrumb alone. The branch numbered them (
HT-01-getting-started.md,HT-90-troubleshooting.md).the bulleted When/Prerequisites/Time template — that last one is the branch's own "stacked bold
labels are a bullet list" rule applied to itself.
A dry-run merge of that branch conflicts in
SKILL.mdandDECISION_LOG.mdand re-bumps to 1.1.5, aversion
mainalready occupies. It carries nothing unsalvaged now and can be deleted.Phases renumbered (write-each-procedure 4 → 5, self-review 5 → 6); the single internal phase
cross-reference in Output updated to "Phases 3-4".
Testing
python tools/validate-plugins/validate.py→OK: all plugin checks passedpython ceh-documentation/scripts/check-semver.py CHANGELOG.md→OK: All version entries are valid semverDocs-only change; no runtime code paths touched.
Checklist
ceh-documentation/README.mdupdated; root README needs no change (its row describes triggers)CROSS_REFERENCES.mdchecked — no existing skill states Markdown rendering rules, nothing to registerplugin.jsonandmarketplace.jsonin the same commit as the contentDECISION_LOG.mdentry 75 records the rebase and the branch's fateKnown consequence
Guides already generated under v3.29.2 have no footers. The skill tells the agent to edit existing
docs in place rather than relocate them, so nothing auto-migrates.
Generated with Claude Code by CEH