# Ascribe documentation

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

## Pages

- [Ascribe documentation](https://ascribed-dev.com/index.md): Guides and references for writing documentation with Ascribe, and the contracts for implementers.
- [Getting started](https://ascribed-dev.com/getting-started.md): Install Ascribe, write a first page, check it, build it, and publish it with Astro.

## Contracts

- [Asset contract](https://ascribed-dev.com/contracts/assets.md): Where assets go in each output and how pages refer to them.
- [ascribe.toml format contract](https://ascribed-dev.com/contracts/content-model.md): The normative contract for the content model file, with the rules a loader enforces and the decisions behind them.
- [JSON report contract](https://ascribed-dev.com/contracts/json-reports.md): The JSON Schemas of what the ascribe commands write with --format json.
- [Output-layout contract](https://ascribed-dev.com/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.
- [Site-render contract](https://ascribed-dev.com/contracts/site-render.md): The markers the site output writes and how a consumer renders them.

## Guides

- [Agents](https://ascribed-dev.com/guides/agents.md): Working on an Ascribe project with an AI coding agent, such as Claude Code, GitHub Copilot, or Cursor, and handing it the problems Ascribe finds.
- [Astro](https://ascribed-dev.com/guides/astro.md): Publishing a site with @ascribed/astro.
- [Drift](https://ascribed-dev.com/guides/drift.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.
- [Editing](https://ascribed-dev.com/guides/editor.md): The VS Code extension, workspaces with several projects, and other editors.
- [The project report](https://ascribed-dev.com/guides/report.md): Reading ascribe report and acting on each section, from the problems and pages it counts to broken external links and the published site's delivery to agents, and running it every week in CI.
- [Review](https://ascribed-dev.com/guides/review.md): Reviewing a pull request as readers will see it, in the page preview, the site preview, or a report from CI, and commenting there.
- [Prose, through Vale](https://ascribed-dev.com/guides/vale.md): Checking your pages' prose with Vale, from Ascribe's quiet preset or your own Vale configuration, in the editor and in ascribe check.

## Reference

- [Command reference](https://ascribed-dev.com/reference/cli.md): The ascribe commands: their options, outputs, and exit codes.
- [ascribe.toml reference](https://ascribed-dev.com/reference/content-model.md): The content model: content types, dimensions, availability, phrases, widgets, and builds.
- [Diagnostics](https://ascribed-dev.com/reference/diagnostics.md): Every problem Ascribe reports, with its code and fix.
- [Directive reference](https://ascribed-dev.com/reference/directives.md): The language: directives, attributes, titles, phrases, links, and images.