Ascribe documentation

Guides and references for writing documentation with Ascribe, and the contracts for implementers.

• Getting started: install Ascribe, write a first page, check it, build it, and publish it with Astro.

• Directive reference: the language: directives, attributes, titles, phrases, links, and images.

• ascribe.toml reference: the content model: content types, dimensions, availability, phrases, widgets, and builds.

• Command reference: ascribe check, build, diff, fmt, and lsp, their options, outputs, and exit codes.

• Ascribe (in main, not yet released)

  Review: reviewing a pull request as readers will see it, in the page preview, the site preview, or a report from CI, and commenting there.

• Ascribe (in main, not yet released)

  Drift: keeping pages from falling behind the code they describe, with code examples taken from tested files.

• Diagnostics: every problem Ascribe reports, with its code and fix.

• Editing: the VS Code extension, workspaces with several projects, and other editors.

• Astro: publishing a site with @ascribed/astro.

For implementers

These contracts say what an emitter writes and what a consumer can rely on. They matter if you’re changing Ascribe’s outputs or writing a consumer, and not if you’re writing documentation with it.

• The ascribe.toml format: the normative contract for the content model file, with the rules a loader enforces and the decisions behind them. The reference above is the guide for writing one.
• Output layout: where ascribe build writes each build’s output, how it records what it wrote, and how it replaces a previous output.
• Assets: where assets go in each output and how pages refer to them.
• Site render: the markers the site output writes and how a consumer renders them. The fixtures are in tests/render/.

The Ascribe specification is the normative definition of the language. The changelog lists what each release changed.