Customising your docs

scaffold seeds a starting set of docs source pages once; after that they belong to the adopting package, not to the kit. This page explains which files are yours to rewrite and where to start.

What's package-owned here

update never rewrites these, no matter how many times it runs:

• getting-started/index.md — the quickstart a new user lands on first.

• getting-started/infrastructure.md and any further page added under docs/src/.

• docs/pages.jl — the navigation tree; add, remove, or reorder entries freely.

• The README body (the badge block and the standard sections between their managed markers are rewritten on sync; everything else is package-owned).

• CITATION.cff — your citation metadata (authors, DOI, version). Seeded once so GitHub renders a "Cite this repository" widget, then never rewritten; edit it as the package is released.

See Infrastructure and template sync for the full managed-versus-package-owned breakdown.

Making it your own

• Replace the seeded quickstart in getting-started/index.md with the package's real installation steps and a runnable first example.

• Add new pages under docs/src/ as the package grows (tutorials, guides, worked examples), then list them in docs/pages.jl.

• Reorder or rename any Getting started entry; pages.jl is read fresh on every docs/make.jl run, so there is no drift to fight.

• Keep or delete this page once it has served its purpose — it is package-owned like the rest of getting-started/.

The kit's own copies of these pages (the ones this documentation site renders) are the worked example: this site is a real adopter of the scaffold, seeded once and then hand-edited the same way any adopting package's docs would be.

What stays managed

• docs/make.jl, the thin caller into the kit's build logic.

• The VitePress theme, config, and components under docs/src/.vitepress/ and docs/src/components/.

• The API reference pages, generated fresh from the module's docstrings on every build rather than stored as source.

• The README standard sections (Contributing, How to cite, Code of conduct) between the standard-sections markers, so their wording stays consistent across adopters. Put package-specific prose outside the markers, and your citation details in CITATION.cff.

Editing a managed file directly works until the next update or template-sync run reverts it — put customisation in the package-owned files above instead. If a package genuinely has to own a managed file, add an EPIAWARE_MANAGED_OVERRIDE comment to it and the sync preserves it; see Infrastructure and template sync.