Docs as code, with the tools docs need.

Ascribe is a toolchain for documentation written as code: Markdown with the structure docs need, checked as you write, and built into a website, plain Markdown, and JSON.

npm install --save-dev @ascribed/cli

Read getting started

The mark: a heavy letter a, with the two change marks of a gutter beside it, on a grid. The mark: a heavy letter a, with the two change marks of a gutter beside it, on a grid.

A page, and what readers see

A page’s source, read from its file in Ascribe’s repository, and the page this site builds from it. The note, tabs, and steps are Ascribe directives.

install.md
---
type: page
title: Install Quill
---

@note {type=tip}: {product} {version} needs Node.js 22 or later.

## Install the package

@variant {pm=npm}:
```sh
npm install quill
```
@variant {pm=pnpm}:
```sh
pnpm add quill
```
@variant {pm=yarn}:
```sh
yarn add quill
```
@end

## Set it up

@steps
1. Create `quill.yaml` in your project's root.
2. Run `quill init`, which checks it.

Install Quill

Quill 3.4.1 needs Node.js 22 or later.

Install the package

npm

npm install quill

pnpm

pnpm add quill

yarn

yarn add quill

Set it up

  1. Create quill.yaml in your project’s root.
  2. Run quill init, which checks it.

The tools of a docs team

npm

npx ascribe build

pnpm

pnpm exec ascribe build

The command above is marked with @variant. The site shows it as tabs, and the plain Markdown and JSON label each version.

Checked like code

Checked

Includes, variants, and page types are part of the Markdown, so one compiler checks them in the editor, on the command line, and in CI. A broken include or link is underlined as you type, like a misspelled import. Here is ascribe check on the page getting started writes, which links to a page that doesn’t exist yet.

Vale can check the prose, too.

ascribe 0.4.5
[ASC036] Error: `configure.md` doesn't exist
    ╭─[ docs/index.md:33:22 ]
    │
 33 │ Next, [configure it](configure.md).
    │                      ──────┬─────
    │                            ╰─────── link-target-missing
    │
    │ Help: Fix the path, or create the file. Names must match exactly, including case, and the file must be inside the project.
────╯
checked 1 file for every build, 1 with problems: 1 error, 0 warnings, 0 advice

Examples from real code

With @snippet, a code example is read from the code’s own file each time a page is checked or built, so it changes when the code does. On a pull request, ascribe drift lists the pages whose examples changed, so someone can reread the text around them.

ascribe 0.4.5
compared with main (94c2212), from its merge base with HEAD (8a43d4b)

Examples that no longer resolve. `ascribe check` reports them too:
  guides/install.md
    code:service/client.py#connect: the file has no region `connect`

Examples that changed. The page shows the new code; check the words around it:
  reference/content-model.md
    code:examples/quill/ascribe.toml#dimensions (+3 −1)

Examples that changed along with the page:
  guides/review.md
    code:examples/quill/ascribe.toml#builds (+1 −0)

Reviewed as pages

Review a pull request as rendered pages, in the site’s preview or VS Code’s, with each change marked and each comment beside its paragraph. Review shows how.

A page of these docs in the site’s preview during review: a changed paragraph is marked, the pull request’s two comments on it are beside it, and the review panel below names the pull request and its one change. A page of these docs in the site’s preview during review: a changed paragraph is marked, the pull request’s two comments on it are beside it, and the review panel below names the pull request and its one change.

Built for AI agents, writing and reading

As writers

  • The project’s rules from ascribe agents sync.
  • The model and the checks through the MCP server.
  • A hook that checks after each edit.
  • Memos keep the reason a page is written its way, for the next person or agent who changes it.

As readers

AGENTS.md
ascribe 0.4.5
<!-- ascribe:agents start (generated by `ascribe agents sync`; edit ascribe.toml, not this block) -->
## Ascribe documentation

The Markdown pages under `docs/` are Ascribe documentation: pages with YAML frontmatter, `@` directives, and `{key}` phrases, checked against the content model in `ascribe.toml`.

After editing a page, run `ascribe check <file> --format concise` and fix every error. Before you finish, run `ascribe check`. `ascribe explain <code>` says what a problem means and how to fix it.

Before writing a page about a subject, run `ascribe search "<words>"` to find where the pages already say it, as readers read them, and link to what's there or extend it instead of saying it again.

Read a block's `@memo` before changing the block, and keep the two together: a memo says why the page is written the way it is, and is never published.

`ascribe outline <page>` lists the memo files about a page and each of its headings: read a memo before changing the block it's about, and keep it.

### Page types

A page says what type it is with `type:` in its frontmatter, first, and its other fields are its type's. A file or folder whose name starts with `_` is a fragment, which pages `@include`, not a page, and names no type.

- `page`: frontmatter `title` (string, required), `description` (string)

### Phrases

Write the phrase (`{product}`), not the text it stands for.

- `{product}`: Quill
- `{cloud}`: Quill Cloud
- `{version}`: 3.4.1
- `{api}`: https://api.quill.dev/v3/

### Directives this project uses

- `@id: <id>` on the line under a heading: an id for links to it that doesn't change with its text
- `@include: <file>.md`, or `@include: <file>.md#<id>` for one section: another file's content, in place
- `@variant {<dimension>=<value>}:` before each arm, and one `@end` after the last: content that differs by a dimension. Here: dimensions `pm` (`npm`, `pnpm`, `yarn`), `deployment` (`cloud`, `self-managed`)
- `@available: <spec>` under a heading or above a block: where it applies, as targets with an optional state and version (`cloud, self-managed`), or a feature's key
- `@note {type=<type>}: <text>`, or `@note:` … `@end` around several blocks: a callout. Here: types `note`, `tip`, `important`, `warning`, `caution`
- `@steps` on the line above an ordered list: the list is a procedure
- `@memo: <text>` under a heading or above a block, or `@memo:` … `@end` around several lines: a note for whoever maintains the page, never published

### Links

Link to the source file, with a relative path such as `../guides/install.md#configure`, not to the site's address. `ascribe outline <page>` lists a page's headings with their ids, and `ascribe link <target> --from <page>` says whether a link works and what to write. A product's message that links to these docs by a permalink can read what the docs will show for it first: `ascribe resolve go:<name>` prints the help a product shows, from the build's `help.json`. Give a heading with a permalink a summary, a sentence or two a product shows with its help: `@summary` on the line above a paragraph of the section that reads well alone, or `@summary: <text>` under the heading and its `@id` when none does, as for a lead-in to a list. Keep it under 300 characters.

### More

To see what a reader of the site gets, not only a reader of the Markdown, run `ascribe resolve <page> --build <name> --emit site`, or call `ascribe_resolve` with `emit: "site"`: the page as the site output gives it to the site, with Ascribe's elements. How to read them: https://ascribed-dev.com/go/reading-site-output/

`ascribe model` shows everything the content model allows. Every directive: https://ascribed-dev.com/go/directives/
<!-- ascribe:agents end -->

What ascribe agents sync writes into an example project’s AGENTS.md.

For engineers, writers, and agents

Where to start depends on what you do.

Engineers

Start with checked like code.

Writing tools in the editor, repository, and CI you already use.

The path for engineers

Writers

Start with the tools of a docs team.

Reuse, variants, versions, and preview, in the same repository as the engineers who review your pages.

The path for writers

Agents

Start with the rules, the checks, and the outputs.

An agent writing pages gets a check to run that always gives the same answer. An agent reading them gets Markdown and an index instead of HTML.

The path for agent builders

Start

  1. Install the command in your project’s folder:

    npm install --save-dev @ascribed/cli
  2. Install the VS Code extension:

    code --install-extension Ascribe.ascribe-vscode

Then follow getting started to set up a project and publish a first page.

Read getting started

Plain files you can leave

  • A page is a Markdown file.
  • The plain Markdown output is CommonMark, with includes and phrases filled in.
  • Ascribe hosts nothing and calls no model.
  • It’s open source under the MPL.

Why Ascribe covers the problems Ascribe solves, and what it doesn’t do.

Early, and open source

Ascribe is before 1.0, so a release can still change behavior. Pin the version. The latest release is 0.4.5. The code, the docs, and the plans are on GitHub, under the Mozilla Public License 2.0.

Ascribe is made by Bryo Studio. Credits says what it’s built on.