docs: reorganise into categorised folders + real docs index + link audit#51
Merged
Conversation
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
DemchaAV
added a commit
that referenced
this pull request
May 24, 2026
…h audit Phase 3 of the documentation work after audit (#50 added the templates-layered/ guide; #51 here restructures the entire docs/ tree and fixes terminology + link hygiene). Reorg — docs/ structure ----------------------- Was: 21 flat .md files in docs/ with no obvious category. Now grouped by purpose, mirroring the personas: docs/ ├── README.md ← NEW real docs index ├── SHOWCASE.md ← renamed from docs/README.md │ (GitHub Pages showcase doc) ├── getting-started.md ← kept flat (high traffic) ├── recipes.md ← kept flat (recipes index) ├── adr/ ← unchanged (8 ADRs) ├── archive/ ← unchanged (3 archived docs) ├── recipes/ ← unchanged (7 recipes) ├── architecture/ ← NEW (5 files moved) │ ├── overview.md ← was architecture.md │ ├── lifecycle.md │ ├── pagination-ordering.md │ ├── canonical-legacy-parity.md │ └── package-map.md ├── operations/ ← NEW (5 files moved) │ ├── benchmarks.md │ ├── logging.md │ ├── performance.md │ ├── production-rendering.md │ └── layout-snapshot-testing.md ├── contributing/ ← NEW (3 files moved) │ ├── extension-guide.md │ ├── implementation-guide.md │ └── release-process.md ├── roadmaps/ ← NEW (3 files moved) │ ├── v1.6-roadmap.md │ ├── migration-v1-4-to-v1-5.md │ └── migration-v1-5-to-v1-6.md └── templates/ ← NEW (groups both surfaces) ├── v1-classic/ ← was docs/templates-v2.md + template-authoring.md │ ├── README.md ← v1.6 "Templates v2" landing │ └── authoring.md ← was template-authoring.md └── v2-layered/ ← was docs/templates-layered/ ├── README.md ├── quickstart.md ├── using-templates.md ├── authoring-presets.md └── contributor-guide.md 20 files moved via `git mv` so the history is preserved. Documentation index — docs/README.md ------------------------------------ The old docs/README.md was about the GitHub Pages showcase site, not a docs index — opening docs/ on GitHub showed the wrong thing. - Renamed old docs/README.md → docs/SHOWCASE.md - Wrote new docs/README.md as the canonical docs landing: persona map + category map + ADR list + recipe list + quick links. v1/v2 terminology — explicit callouts ------------------------------------- The codebase has TWO surfaces both casually called "v2": - The v1.6 rebuilt templates (CvSpec / CvBuilder / *Presets) which the project calls "Templates v2" internally (ADR-0011). - The newer layered cv/v2/ architecture introduced in PRs #45-#49. Added clarifying callouts at the top of: - docs/templates/v1-classic/README.md — "this is the v1.6 surface; for the newer layered pattern see v2-layered/" - docs/templates/v1-classic/authoring.md — same callout - docs/templates/v2-layered/README.md — "this is the layered architecture; NOT the older v1.6 'Templates v2'" Both surfaces are still shipped and supported; neither is deprecated. The callouts just kill the confusion. CONTRIBUTING.md update ---------------------- The "New built-in template" section now opens with a fork: - For a NEW template family from scratch → layered architecture (with link to contributor-guide.md) - For a new preset inside an existing v1-classic family → keep using BusinessTheme + CvBuilder + the existing presets pattern Plus a "📚 Map of template docs" pointer to docs/README.md so contributors don't have to guess. Orphan resolution ----------------- - docs/performance.md was nowhere-linked. Moved to operations/ and indexed from docs/README.md. - docs/recipes/shapes.md was nowhere-linked-from-root-README but IS linked from recipes.md (the recipe index). Root README now links recipes.md so it's discoverable. - ADR numbering gap (0005-0010 missing) explained inline in docs/README.md as a note next to the ADR list. Link integrity -------------- - sed sweep across 58 .md files updated every absolute `docs/X.md` reference to its new categorised path. - Internal relative links inside moved files (e.g. `./benchmarks.md` from within docs/architecture/) updated by hand for every affected file. - Final automated sweep verifies **zero broken markdown links** repo-wide. Tech accuracy spot-check ------------------------ Sampled 4 high-traffic docs against the current code: - getting-started.md — every referenced class (DocumentSession, BusinessTheme, etc.) exists in src/. - templates/v1-classic/authoring.md — every layout class (SingleColumn, TwoColumnSidebar, ThreeColumnMagazine, etc.) exists. - templates/v1-classic/README.md — accurate. - contributing/extension-guide.md — accurate. No stale class references found. Root README update ------------------ Documentation section reorganised: - New "📚 Full docs index" link to docs/README.md. - Templates split into v2-layered (new) and v1-classic (legacy but shipped) with cross-link to authoring guides. - Sub-grouped: Templates / Architecture & operations / Recipes & examples / Contributing & releases. No engine, source, or test changes. Pure documentation.
DemchaAV
force-pushed
the
feature/docs-reorg-and-audit
branch
from
97133d0 to
95c00e8
Compare
…h audit Phase 3 of the documentation work after audit (#50 added the templates-layered/ guide; #51 here restructures the entire docs/ tree and fixes terminology + link hygiene). Reorg — docs/ structure ----------------------- Was: 21 flat .md files in docs/ with no obvious category. Now grouped by purpose, mirroring the personas: docs/ ├── README.md ← NEW real docs index ├── SHOWCASE.md ← renamed from docs/README.md │ (GitHub Pages showcase doc) ├── getting-started.md ← kept flat (high traffic) ├── recipes.md ← kept flat (recipes index) ├── adr/ ← unchanged (8 ADRs) ├── archive/ ← unchanged (3 archived docs) ├── recipes/ ← unchanged (7 recipes) ├── architecture/ ← NEW (5 files moved) │ ├── overview.md ← was architecture.md │ ├── lifecycle.md │ ├── pagination-ordering.md │ ├── canonical-legacy-parity.md │ └── package-map.md ├── operations/ ← NEW (5 files moved) │ ├── benchmarks.md │ ├── logging.md │ ├── performance.md │ ├── production-rendering.md │ └── layout-snapshot-testing.md ├── contributing/ ← NEW (3 files moved) │ ├── extension-guide.md │ ├── implementation-guide.md │ └── release-process.md ├── roadmaps/ ← NEW (3 files moved) │ ├── v1.6-roadmap.md │ ├── migration-v1-4-to-v1-5.md │ └── migration-v1-5-to-v1-6.md └── templates/ ← NEW (groups both surfaces) ├── v1-classic/ ← was docs/templates-v2.md + template-authoring.md │ ├── README.md ← v1.6 "Templates v2" landing │ └── authoring.md ← was template-authoring.md └── v2-layered/ ← was docs/templates-layered/ ├── README.md ├── quickstart.md ├── using-templates.md ├── authoring-presets.md └── contributor-guide.md 20 files moved via `git mv` so the history is preserved. Documentation index — docs/README.md ------------------------------------ The old docs/README.md was about the GitHub Pages showcase site, not a docs index — opening docs/ on GitHub showed the wrong thing. - Renamed old docs/README.md → docs/SHOWCASE.md - Wrote new docs/README.md as the canonical docs landing: persona map + category map + ADR list + recipe list + quick links. v1/v2 terminology — explicit callouts ------------------------------------- The codebase has TWO surfaces both casually called "v2": - The v1.6 rebuilt templates (CvSpec / CvBuilder / *Presets) which the project calls "Templates v2" internally (ADR-0011). - The newer layered cv/v2/ architecture introduced in PRs #45-#49. Added clarifying callouts at the top of: - docs/templates/v1-classic/README.md — "this is the v1.6 surface; for the newer layered pattern see v2-layered/" - docs/templates/v1-classic/authoring.md — same callout - docs/templates/v2-layered/README.md — "this is the layered architecture; NOT the older v1.6 'Templates v2'" Both surfaces are still shipped and supported; neither is deprecated. The callouts just kill the confusion. CONTRIBUTING.md update ---------------------- The "New built-in template" section now opens with a fork: - For a NEW template family from scratch → layered architecture (with link to contributor-guide.md) - For a new preset inside an existing v1-classic family → keep using BusinessTheme + CvBuilder + the existing presets pattern Plus a "📚 Map of template docs" pointer to docs/README.md so contributors don't have to guess. Orphan resolution ----------------- - docs/performance.md was nowhere-linked. Moved to operations/ and indexed from docs/README.md. - docs/recipes/shapes.md was nowhere-linked-from-root-README but IS linked from recipes.md (the recipe index). Root README now links recipes.md so it's discoverable. - ADR numbering gap (0005-0010 missing) explained inline in docs/README.md as a note next to the ADR list. Link integrity -------------- - sed sweep across 58 .md files updated every absolute `docs/X.md` reference to its new categorised path. - Internal relative links inside moved files (e.g. `./benchmarks.md` from within docs/architecture/) updated by hand for every affected file. - Final automated sweep verifies **zero broken markdown links** repo-wide. Tech accuracy spot-check ------------------------ Sampled 4 high-traffic docs against the current code: - getting-started.md — every referenced class (DocumentSession, BusinessTheme, etc.) exists in src/. - templates/v1-classic/authoring.md — every layout class (SingleColumn, TwoColumnSidebar, ThreeColumnMagazine, etc.) exists. - templates/v1-classic/README.md — accurate. - contributing/extension-guide.md — accurate. No stale class references found. Root README update ------------------ Documentation section reorganised: - New "📚 Full docs index" link to docs/README.md. - Templates split into v2-layered (new) and v1-classic (legacy but shipped) with cross-link to authoring guides. - Sub-grouped: Templates / Architecture & operations / Recipes & examples / Contributing & releases. No engine, source, or test changes. Pure documentation.
DemchaAV
force-pushed
the
feature/docs-reorg-and-audit
branch
from
95c00e8 to
782a5fa
Compare
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
2 participants
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.
Summary
Acts on the documentation audit findings: reorganises
docs/from21 flat files into 6 categorised folders, replaces the misleading
docs/README.md(which was about GitHub Pages) with a realdocumentation index, kills the v1/v2 terminology confusion via
explicit callouts, and fixes every broken link the reshuffle
created.
Before / After
Before —
docs/was a flat dump:After —
docs/grouped by purpose:Key changes
docs/README.mdis now a real docs index — categorisedlanding with persona map, category map, ADR list, recipe list,
and quick links. The previous
docs/README.md(about theGitHub Pages showcase) is renamed to
docs/SHOWCASE.md.20 files moved via
git mvso history is preserved. Sedsweep across 58 .md files updated every absolute
docs/X.mdreference. Internal relative links (e.g.
./lifecycle.mdinsidethe moved
architecture/overview.md) fixed by hand for everyaffected file.
v1/v2 terminology confusion killed with explicit
> ⚠️ Naming clarificationcallouts at the top of:templates/v1-classic/README.mdtemplates/v1-classic/authoring.mdtemplates/v2-layered/README.mdBoth surfaces explained as coexisting, neither deprecated, with
bidirectional cross-links so a reader who lands on one knows
the other exists.
CONTRIBUTING.md "New built-in template" section now opens
with a fork: NEW family → layered architecture
(
docs/templates/v2-layered/contributor-guide.md); NEW presetinside existing family → v1-classic pattern. Plus a "📚 Map of
template docs" pointer to
docs/README.md.Orphans resolved.
docs/performance.md(previouslynowhere-linked) is now in
operations/and indexed.docs/recipes/shapes.mdwas only linked viarecipes.md, whichis now linked from root README, so discoverable.
ADR numbering gap (0005-0010 missing) explained as a note
in
docs/README.md— those numbers were reserved during a v1.5restructure that landed under ADR 0011 instead.
Root README.md documentation section restructured:
"📚 Full docs index" pointer at the top, then categorised
sub-groups (Templates / Architecture & operations / Recipes &
examples / Contributing & releases).
Tech accuracy spot-check
Sampled 4 high-traffic docs against the current code:
getting-started.md— every referenced class(
DocumentSession,BusinessTheme, etc.) exists insrc/templates/v1-classic/authoring.md— every layout class(
SingleColumn,TwoColumnSidebar,ThreeColumnMagazine, etc.)exists
templates/v1-classic/README.md— accuratecontributing/extension-guide.md— accurateNo stale class references found.
What's NOT changed
relocation + link fixes).
as coexisting.
Test plan
mvn javadoc:javadocclean (no doc-level errors)git mvused everywhere so history preserveddocs/README.mdindex for completeness