Skip to content

docs(documentation): add page navigation and markdown rendering rules (v3.29.3) - #74

Merged
cheneeheng merged 2 commits into
mainfrom
docs/guide-page-furniture
Aug 11, 2026
Merged

docs(documentation): add page navigation and markdown rendering rules (v3.29.3)#74
cheneeheng merged 2 commits into
mainfrom
docs/guide-page-furniture

Conversation

@cheneeheng

Copy link
Copy Markdown
Owner

What

Adds Phase 4 — Page furniture and markdown that renders to
ceh-documentation:user-operator-guide, and releases it as v3.29.3.

  • A breadcrumb under the H1 and a prev/next footer at the bottom of every subfolder page.
  • The H1 repeats the file's ID (# HT-02 — Reset a password), so a printed or pasted page still
    says where it came from.
  • index.md is the hub: no footer, lists every page grouped by subfolder in NN order.
  • Markdown line-break rules — the single-newline trap, blank lines around every block element,
    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.md from a search or a pasted path had no way back to the index and no way
on to HT-03 — the numbering that encodes reading order was visible only to whoever listed the
directory.

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 branch
that solved the v3.29.2 naming problem differently (prefix by audience, HT/OP only, numbering
global 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:

  • Chains run per subfolder, not per audience prefix, so prev/next point at siblings and need no
    ../. Only the breadcrumb climbs.
  • Root-level pages are unnumbered under the released scheme, so they join no chain and take the
    breadcrumb alone. The branch numbered them (HT-01-getting-started.md, HT-90-troubleshooting.md).
  • Kept verbatim in substance: the H1-repeats-ID rule, the line-break table, the blank-line rules, and
    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.md and DECISION_LOG.md and re-bumps to 1.1.5, a
version main already 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.pyOK: all plugin checks passed
  • python ceh-documentation/scripts/check-semver.py CHANGELOG.mdOK: All version entries are valid semver
  • Phase headings verified sequential 1-6 with no stale cross-references.

Docs-only change; no runtime code paths touched.

Checklist

  • ceh-documentation/README.md updated; root README needs no change (its row describes triggers)
  • CROSS_REFERENCES.md checked — no existing skill states Markdown rendering rules, nothing to register
  • Version bumped in plugin.json and marketplace.json in the same commit as the content
  • DECISION_LOG.md entry 75 records the rebase and the branch's fate
  • Validator green

Known 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

…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
@cheneeheng
cheneeheng merged commit 40f9549 into main Aug 11, 2026
1 check passed
@cheneeheng
cheneeheng deleted the docs/guide-page-furniture branch August 11, 2026 18:14
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