How NextPDF documentation is structured

At a glance

The NextPDF manual follows a fixed contract. Each page has one topic, one Diataxis mode, and one page kind. Each page kind has a required set of level-2 headings. A small set of manifests and gates keeps the structure consistent as the manual grows.

This page outlines that system so you can place your contribution correctly. The full normative contract, including the exact heading lists, citation rules, and gate-wiring procedure, lives in the internal governance document docs/style/expansion-standard.md. Read this page first. Consult that document when you author.

Choosing a page kind

Apply these rules in order to decide whether to add a page or extend one:

1. If the material is a distinct topic that a reader would not expect on the existing page, add a new page.
2. If the material completes a topic the existing page already owns, extend that page.
3. If the material is deep detail that would inflate an install, quickstart, or task page, move it to a separate page and link to it.
4. Otherwise, extend the existing page.

After you know the page should exist, set its Diataxis mode. The mode fixes the page kind:

• Tutorial teaches a learner. Use a task guide written as a recipe.
• How-to helps a competent reader finish a task. Use a task guide, a server API guide, or a software development kit guide.
• Reference states exact facts. Use an API reference or an index page.
• Explanation builds understanding. Use a developer guide or a premium feature guide.

Plain language is the baseline for every mode, not a separate mode.

The page-kind catalog

The manual contract recognizes these kinds. Reuse an existing kind whenever your page includes an API table. Introduce a new label-only kind only for a page with no API table.

• Index kinds: section-index, api-index, extension-index.
• Reference kind: api-reference. Reuse this for any page with the standard API table, including server and Python SDK references.
• Explanation kind: developer-guide. Reuse this for architecture, lifecycle, and extension-point prose, including server and Python SDK guides.
• New label-only kinds: premium-feature-guide and task-guide, both for pages without an API table.

Every page opens with ## At a glance. Every api-reference page includes the shared API table and the Development notes heading. Required headings are level-2 headings, each on its own line. You may add more headings below them.

Authoring checklist

When you write a page, satisfy both checklists. The internal standard states each item normatively and links to its supporting standard.

Developer-friendliness:

• Source runnable examples from examples/ or tests/Cookbook, and give each fenced block a title= info string.
• State prerequisites in front-matter and in the opening.
• Show the expected output for any sample that produces one.
• Keep blocks ready to copy and paste: one language per block, full names on first use, and no trailing prompt characters.
• Show secure-by-default code: production samples use try/catch with the most specific NextPDF exception and never an empty catch.
• End with onward links and set front-matter related:.

Translation readiness:

• Write one idea per sentence so machine translation stays bounded.
• Keep headings and labels short because most target languages expand.
• Avoid idioms.
• Keep symbol names, config keys, CLI flags, and exception names in code formatting; standards names such as PDF/A-4, PAdES, and eIDAS are never translated.
• Set i18n_ready and xliff_segments honestly, and write in Unicode NFC.

For voice, code-sample, terminology, and citation style, follow the ratified style override sheet referenced by the internal standard.

Gate wiring

Wire in a new page with this ordered procedure:

1. Scaffold the page so its front-matter matches the site schema.
2. Author the body to the page kind’s required headings.
3. Add a { path, owner, kind, headings[] } entry to docs/manual-contract.json. The path is relative to src/content/docs, uses forward slashes, and carries no leading slash and no ...
4. For an API reference, add the page’s symbols to docs/api-coverage-manifest.json; each symbol must appear in the page and exist in source.
5. Update docs/source-manifest.json only when the page comes from a new source repository.
6. Add the page to the correct sidebar group in astro.config.mjs as an explicit entry.
7. Add a locale-coverage row with all seventeen locale cells set to missing for an English-only page.
8. Run the documentation gates, the build, and the performance budget.

Site-owned pages live under src/content/docs, set owner to nextpdf-docs, and never carry an aggregation marker. Aggregated pages come from a source repository. Their publish flag lives in the source front-matter, so you edit them there, not here.

See also

• Integrations: the largest worked example of the manual structure across many packages.
• The internal governance document docs/style/expansion-standard.md holds the full contract: exact heading lists for every page kind, the citation rules, and the complete gate-wiring procedure.