Comprehensive docs for the engine, the templates, and the contribution workflow. Below is the map — pick your path.
If you're new to GraphCompose entirely, start at the root README for the project overview, then come back here.
| You are… | Read |
|---|---|
| New to GraphCompose — what is it, how do I render my first PDF | Getting started → Hello world in root README |
| Author rendering a CV with your own data | Templates v2 (layered) — quickstart |
| Designer / author wanting a custom visual style for CVs | Templates v2 (layered) — authoring presets |
Author using legacy v1.6 templates (CV / cover-letter / invoice / proposal still using *Spec + builders) |
Templates v1-classic — landing |
| Contributor adding a new template family to the library | Templates v2 (layered) — contributor guide |
| Contributor extending the engine (new node type, new backend handler) | Extension guide → Implementation guide |
| Operator running GraphCompose in production | Production rendering → Performance → Logging |
- getting-started.md — DSL vs templates, first-render walk-through, decision tree.
- templates/v2-layered/ — 🆕 canonical going-forward pattern (CV is the reference implementation):
data/theme/components/widgets/presets. - templates/v1-classic/ — the spec/builder/presets surface used by v1.6 CV, cover-letter, invoice, proposal templates. Still ships, still supported.
- architecture/overview.md — high-level system architecture (engine + DSL + templates + backends).
- architecture/lifecycle.md — the document lifecycle from
GraphCompose.document(...)throughbuildPdf(). - architecture/pagination-ordering.md — how nodes are paginated and ordered.
- architecture/package-map.md — what's in which package.
- architecture/canonical-legacy-parity.md — canonical (v1.5+) vs legacy compatibility matrix.
- operations/production-rendering.md — server-side rendering, streaming, thread safety.
- operations/performance.md — perf characteristics + tuning.
- operations/benchmarks.md — how to run benchmarks; reference numbers.
- operations/logging.md — logger configuration, what each logger emits.
- operations/layout-snapshot-testing.md — snapshot-based layout regression testing.
- contributing/extension-guide.md — add a new node type, backend handler, or theme primitive.
- contributing/implementation-guide.md — internal engine notes for contributors hacking on layout / measurement / pagination.
- contributing/release-process.md — versioning, tag procedure, Maven Central publication.
- roadmaps/v1.6-roadmap.md — current development roadmap.
- roadmaps/migration-v1-5-to-v1-6.md — upgrade guide for v1.5 → v1.6.
- roadmaps/migration-v1-4-to-v1-5.md — upgrade guide for v1.4 → v1.5.
- recipes.md — index of all recipes.
- recipes/shape-as-container.md — shapes that hold child content.
- recipes/transforms.md — rotation, scaling, skewing.
- recipes/tables.md — tabular layouts.
- recipes/themes.md — custom themes.
- recipes/streaming.md — streaming PDFs to HTTP responses.
- recipes/extending.md — extension patterns by example.
Numbered, dated decisions about non-trivial design choices. Read these when you need to understand why a piece of the system looks the way it does.
- adr/0001-shape-as-container.md — shape nodes as content containers.
- adr/0002-theme-unification.md — single canonical theme model.
- adr/0003-api-stability-and-internal-marker.md — public-API guarantees +
@Internalmarker. - adr/0004-pdf-handler-spi-extension.md — PDF render handler SPI.
- adr/0011-templates-v2-architecture.md — the v1.6 templates restructure (spec/builder/presets/themes); superseded for CV + cover letter by 0015.
- adr/0012-nested-list-evolution.md — nested list rendering evolution.
- adr/0013-composed-table-cell.md — composed table cell model.
- adr/0014-controlled-absolute-placement.md — controlled absolute placement strategy.
- adr/0015-layered-template-architecture.md — the layered
cv.v2/coverletter.v2authoring model (current standard); supersedes the preset/builder portion of 0011.
ADR numbering gap (0005–0010) is intentional — those numbers were reserved during a v1.5 restructure that landed under ADR 0011 instead of multiple smaller records. No deleted ADRs.
- SHOWCASE.md — how the GitHub Pages showcase is built and how to add new examples to it. (Not documentation about GraphCompose itself — this is meta-doc about the website at https://demchaav.github.io/GraphCompose/.)
- archive/ — old migration guides and roadmaps kept for historical reference. Not part of the live doc set.