docs(templates-layered): comprehensive guide for v2 layered architecture#50
Merged
Merged
Conversation
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
5 tasks
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.
…rchitecture
Closes the documentation gap surfaced after Phase 3: until now,
information about the cv/v2 layered pattern was scattered between
package-info JavaDocs and an in-package AUTHORS.md. New
contributors had nowhere to land for a coherent walkthrough.
Adds docs/templates-layered/ with five focused docs, one per
reader persona:
- README.md landing page + "you are here" persona map
- quickstart.md 5-min orientation + 5-layer diagram
+ working render-a-CV example
- using-templates.md builder API, section types, slots,
theme variants, common patterns
(incl. persona-neutral teacher example)
- authoring-presets.md widget cookbook, anatomy of a preset,
full worked CardStyle example,
when-to-go-inline guidance
- contributor-guide.md 5-layer convention, package map,
naming rules, walkthrough for adding
invoice-v2 / cover-letter-v2 family,
test + doc + PR review checklist
Total: 1320 lines across 5 docs. Each doc has a TOC and
cross-references the others.
README.md updated with a new "Documentation" entry pointing to the
landing page and four persona-specific links. Existing v1 surface
docs (template-authoring.md, templates-v2.md) flagged as covering
the legacy surface; both still valid.
No engine, source, or test changes. Pure documentation.
DemchaAV
force-pushed
the
feature/docs-templates-layered
branch
from
1f16af9 to
d3f28d5
Compare
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
added a commit
that referenced
this pull request
May 24, 2026
…h audit (#51) 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.
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
Adds the documentation pack that closes the «как авторам разрабатывать
шаблоны, что переиспользовать, как написать свой» story for the new
layered template architecture (
cv/v2).Until now, information was scattered between in-package JavaDoc
(
package-info.java) and an in-packageAUTHORS.md. Newcontributors had nowhere to land for a coherent walkthrough.
What's new —
docs/templates-layered/Five focused docs, one per reader persona. Each has a TOC and
cross-links to the others.
README.mdquickstart.mdusing-templates.mdauthoring-presets.mdcontributor-guide.mdCoverage by persona
Highlights
components / widgets / presets at a glance.
(teacher) CV showing the API isn't dev-biased.
preset using existing widgets + 2 inline DSL calls. Demonstrates
"compose, don't subclass".
package layout, naming rules, test + doc + PR review checklist.
What changes elsewhere
README.mdgains a new "Documentation" entry pointing todocs/templates-layered/README.mdplus four persona-specificlinks.
docs/template-authoring.mdanddocs/templates-v2.mdare flagged as covering the legacy v1 surface (still valid for
v1 packages).
What's NOT changed
— they describe the v1 surface and remain accurate for that.
Test plan
(relative links resolve, code blocks highlight, tables
align)
paths) resolves to a real file in the repo