> For the complete documentation index, see [llms.txt](https://ascribed-dev.com/docs/llms.txt). This documentation describes Ascribe 0.4.4. Anything marked in main, not yet released isn't in that release yet.

# Ascribe documentation

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

Everyone starts with [Getting started](https://ascribed-dev.com/docs/getting-started.md): it installs Ascribe, and writes, checks, builds, and previews a first page. From there, each path below is a few pages in order, for what you came to do.

## For engineers

Keep the docs in the repository, checked like the code and changed with it.

1. [Checks in CI](https://ascribed-dev.com/docs/checks/ci.md): check every pull request with the command the editor runs.
2. [Show an example from the code](https://ascribed-dev.com/docs/examples/snippets.md): take a page's code examples from tested files, so they change when the code does.
3. [Report the pages whose examples changed](https://ascribed-dev.com/docs/examples/drift.md): find the pages whose examples moved while their words didn't.
4. [Attach the HTML preview to every pull request](https://ascribed-dev.com/docs/review/ci-report.md): let anyone review a change as readers will see it, without a checkout.

## For writers

Write and review in the editor, and write a thing once for every reader.

1. [Editing](https://ascribed-dev.com/docs/editor.md) and [the preview](https://ascribed-dev.com/docs/editor/preview.md): the VS Code extension, its checks as you type, and the page as readers will see it.
2. [Content that varies](https://ascribed-dev.com/docs/writing/variants.md): one page for readers on different platforms or products.
3. [Phrases](https://ascribed-dev.com/docs/writing/inline.md#phrases) and [includes](https://ascribed-dev.com/docs/writing/directives.md#include): write a name or a passage once, and use it on every page.
4. [Set up a glossary](https://ascribed-dev.com/docs/content-model/glossary.md) and [page templates](https://ascribed-dev.com/docs/templates.md): link every page's terms to their definitions, and start a page of a known kind from a template.
5. [Review in the preview](https://ascribed-dev.com/docs/editor/review.md): what a change did, and a pull request's comments, beside the page.

## For agent builders

Give the agents that write your docs the project's rules and checks, and the agents that read them what they need.

1. [Write the agent files](https://ascribed-dev.com/docs/agents/instructions.md): `ascribe agents sync` writes your project's rules where agents read them on their own.
2. [Set up the MCP server](https://ascribed-dev.com/docs/agents/mcp.md) and [check an agent's edits with hooks](https://ascribed-dev.com/docs/agents/hooks.md): the checks as tools, and run after each edit.
3. [Publish for AI agents](https://ascribed-dev.com/docs/astro/agents.md): `llms.txt` and a Markdown version of every page, for the agents that read the docs.
4. [Help entries](https://ascribed-dev.com/docs/astro/reference.md#help-entries): each [permalink](https://ascribed-dev.com/docs/glossary.md#permalink)'s section as JSON, for an agent in your product.

## Start

- [Getting started](https://ascribed-dev.com/docs/getting-started.md): install Ascribe, write a first page, check it, build it, see it, and publish it with Astro.
- [Install](https://ascribed-dev.com/docs/install.md): every way to install `ascribe`, with npm or on your path without Node.

## Write

- [Directive syntax](https://ascribed-dev.com/docs/writing/syntax.md): the language: how a directive is written, its attributes, forms, titles, and what it applies to.
- [Directive reference](https://ascribed-dev.com/docs/writing/directives.md): each built-in directive, its attributes, and its rules.
- [Phrases, links, and images](https://ascribed-dev.com/docs/writing/inline.md) and [frontmatter](https://ascribed-dev.com/docs/writing/frontmatter.md): the rest of what a page writes.
- [Content that varies](https://ascribed-dev.com/docs/writing/variants.md): writing one page for readers on different platforms or products, with alternatives, [availability](https://ascribed-dev.com/docs/glossary.md#availability), and a build for each audience.
- [Memos](https://ascribed-dev.com/docs/writing/memos.md): keeping the reason a page is written the way it is beside it, for the people and agents who change it, and never for its readers.
- [Glossaries](https://ascribed-dev.com/docs/content-model/glossary.md): setting up a glossary, so every page links the terms it uses to their definitions.
- [Page templates](https://ascribed-dev.com/docs/templates.md): starting a page of a known kind, such as a how-to, from a template and a guide to what goes in it.
- [Examples and drift](https://ascribed-dev.com/docs/examples.md): keeping pages from falling behind the code they describe, with code examples taken from tested files and a report of the pages whose examples changed.
- [Link to your API reference](https://ascribed-dev.com/docs/openapi.md): linking a guide to an operation in your OpenAPI spec, checked against the spec and written as the operation's address.
- [Editing](https://ascribed-dev.com/docs/editor.md): the VS Code extension, workspaces with several projects, and other editors.

## Check

- [Checks in CI](https://ascribed-dev.com/docs/checks/ci.md): checking every pull request with the same command the editor runs, and the formatting check, in GitHub Actions.
- [Prose, through Vale](https://ascribed-dev.com/docs/checks/vale.md): checking your pages' prose with Vale, in the editor and in `ascribe check`.
- [The project report](https://ascribed-dev.com/docs/checks/report.md): what state the whole project is in, from the problems and pages it counts to the published site, and running it every day in CI.
- [Diagnostics](https://ascribed-dev.com/docs/checks/diagnostics.md): every problem Ascribe reports, with its code and fix.

## Review

- [Review](https://ascribed-dev.com/docs/review.md): reviewing a pull request as readers will see it, in the [page preview](https://ascribed-dev.com/docs/glossary.md#page-preview), the [site preview](https://ascribed-dev.com/docs/glossary.md#site-preview), or the [HTML preview](https://ascribed-dev.com/docs/glossary.md#html-preview) from CI, and commenting there.

## Publish

- [Astro](https://ascribed-dev.com/docs/astro.md): publishing a site with `@ascribed/astro`.
- [Navigation](https://ascribed-dev.com/docs/navigation.md): the order a project's sections and pages come in, from `ascribe.nav` or the default, and their labels, which every sidebar is drawn from.
- [Publishing](https://ascribed-dev.com/docs/publishing.md): what a project tells search engines and AI crawlers about its pages, and what it delivers to agents.
- [Keep the addresses you've published](https://ascribed-dev.com/docs/publishing/redirects.md): recording where a page went when it moves or goes, so a link to its old address still leads somewhere.
- [Permalinks](https://ascribed-dev.com/docs/permalinks.md): giving a section an address your product can link to that keeps working when the docs move, checking those links in the product's CI, and moving, aliasing, or retiring one.
- [Publish a site for each version](https://ascribed-dev.com/docs/versions.md): building the docs of every version a reader can be on from one source, a site for each [release line](https://ascribed-dev.com/docs/glossary.md#release-line), and moving them on when a line ships.

## Agents

- [Agents](https://ascribed-dev.com/docs/agents.md): helping an AI coding agent write and fix pages, with instructions it reads on its own and a skill that teaches it the check-and-fix loop.

## Reference

- [`ascribe.toml` reference](https://ascribed-dev.com/docs/content-model.md): the [content model](https://ascribed-dev.com/docs/glossary.md#content-model): content types, [dimensions](https://ascribed-dev.com/docs/glossary.md#dimension), availability, phrases, widgets, and builds.
- [Command reference](https://ascribed-dev.com/docs/command.md): every `ascribe` command, its options, outputs, and exit codes.
- [Files Ascribe writes](https://ascribed-dev.com/docs/command/project-files.md): every file Ascribe puts in a project, and which to commit.
- [Element library reference](https://ascribed-dev.com/docs/astro/elements.md): the custom elements a site draws, and the CSS custom properties that theme them.
- [Glossary](https://ascribed-dev.com/docs/glossary.md): the terms these docs use.

## 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](https://ascribed-dev.com/docs/contracts/content-model.md): the normative contract for the content model file, with the rules a loader enforces and the decisions behind them. The [reference](https://ascribed-dev.com/docs/content-model.md) above is where to look up a key while writing one.
- [Output layout](https://ascribed-dev.com/docs/contracts/output-layout.md): where `ascribe build` writes each build's output, how it records what it wrote, and how it replaces a previous output.
- [Assets](https://ascribed-dev.com/docs/contracts/assets.md): where assets go in each output and how pages refer to them.
- [Navigation](https://ascribed-dev.com/docs/contracts/navigation.md): what `_ascribe/nav.json` holds, the sections and pages in order with their labels, and how a site draws a sidebar from it.
- [Archive](https://ascribed-dev.com/docs/contracts/archive.md): what `ascribe versions export` writes into a folder, and what each page holds.
- [JSON reports](https://ascribed-dev.com/docs/contracts/json-reports.md): the schemas of what the commands write with `--format json`.
- [The permalinks list](https://ascribed-dev.com/docs/contracts/permalinks-list.md): the format of `ascribe.permalinks`, the list of a project's permalinks a product can check its links against.
- [Tested examples](https://ascribed-dev.com/docs/contracts/tested-examples.md): the formats of `ascribe.examples.toml` and of the observation `ascribe observe` writes beside it.
- [Site render](https://ascribed-dev.com/docs/contracts/site-render.md): the markers the site output writes and how a consumer renders them. The fixtures are in [`tests/render/`](https://github.com/ascribed-dev/ascribe/tree/main/tests/render/).

The [Ascribe specification](https://github.com/ascribed-dev/ascribe/blob/main/SPEC.md) is the normative definition of the language. The [changelog](https://github.com/ascribed-dev/ascribe/blob/main/CHANGELOG.md) lists what each release changed.