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
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.
---
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
- Create
quill.yamlin your project’s root. - Run
quill init, which checks it.
The tools of a docs team
- Reuse with
@includeand phrases. - Variants by platform, product, or package manager with
@variant, shown as tabs. - Availability and versions: one source, a build for each release line.
- A glossary that links terms to their definitions.
- Page types and templates, from a content model in
ascribe.toml. - Notes, steps, and details.
- A page preview and a site preview in VS Code.
- Permalinks that keep working when a section moves.
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.
[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 adviceExamples 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.
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.

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
llms.txt.- A Markdown version of every page.
- Each permalink’s help as JSON.
- An index of the docs written into the product’s
AGENTS.md.
<!-- 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.
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.
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.
Start
-
Install the command in your project’s folder:
npm install --save-dev @ascribed/cli -
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.
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.