Ascribe documentation

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

Ascribe checks and builds documentation written as code: Markdown pages with @ directives, checked against a content model in ascribe.toml, and built into a website, plain Markdown, and JSON. Everyone starts with Getting started: 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. How Ascribe works shows the whole system on one page: what you write, what the checks and builds do with it, and where the same checks run. Why Ascribe says what problems it answers, and which it doesn’t.

What you need and what it doesn’t do

Ascribe needs:

• Node.js 24 or later, or none. @ascribed/cli installs ascribe with npm or pnpm; Homebrew, the install script, and a release’s archive put it on your path without Node (Install Ascribe).
• A platform it runs on: macOS on Apple silicon, Linux, or Windows, and not an Intel Mac (Platforms).
• VS Code, to write and review in the editor. The extension is for VS Code; another editor gets the checks from the language server, without the preview.
• GitHub, for review comments. Comments are the pull request’s own, on GitHub or GitHub Enterprise Server, so review on another host shows what changed and no comments (Signing in to GitHub).
• Astro, for the site. @ascribed/astro publishes it (Ways to publish).

It doesn’t:

• Translate. A project is written in one language. A translation is a second project, under its own base path, and one site can hold both; nothing says which of its pages are behind the source.
• Host. It builds files, and whatever serves your site now serves them (Deploy the site).
• Work with another site generator out of the box. Another generator can read the site output, as the contracts fix it, but renders its markers, and does what the Astro integration does beyond rendering, itself.

Who does what

A docs team sets Ascribe up in this order: the docs lead creates the project, the engineer who owns CI and the site wires it in, and then writers write and reviewers review. Each role installs only what its work needs.

A writer who reviews, or a reviewer with a checkout and VS Code, reviews in the page preview instead: Review a pull request.

For engineers

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

1. Check pull requests in CI: check every pull request with the command the editor runs.
2. Show an example from the code: take a page’s code examples from tested files, so they change when the code does.
3. Report the pages whose examples changed: find the pages whose examples moved while their words didn’t.
4. Attach the HTML preview to every pull request: 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 and the preview: the VS Code extension, its checks as you type, and the page as readers will see it.
2. Content that varies: one page for readers on different platforms or products.
3. Write it once: write a name once as a phrase and a passage once as a fragment, and use them on every page.
4. Set up a glossary and page templates: link every page’s terms to their definitions, and start a page of a known kind from a template.
5. Check prose with Vale and a published style guide: check your prose as you save, and hold it to your style guide, such as Google’s or Microsoft’s.
6. Review in the preview: what a change did, and a pull request’s comments, beside the page.
7. Keep pages current: give each page an owner and a date it’s next due to be checked, and see which pages are overdue.

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: ascribe agents sync writes your project’s rules where agents read them on their own.
2. Set up the MCP server and check an agent’s edits with hooks: the checks as tools, and run after each edit.
3. Publish for AI agents: llms.txt and a Markdown version of every page, for the agents that read the docs.
4. Help entries: each permalink’s section as JSON, for an agent in your product.

Start

• Getting started: install Ascribe, write a first page, check it, build it, see it, and publish it with Astro.
• How Ascribe works: the whole system on one page, from the pages you write to the published site.
• Install Ascribe: every way to install ascribe, with npm or on your path without Node.

Write

• Directive syntax: the language: how a directive is written, its attributes, forms, titles, and what it applies to.
• Directive reference: each built-in directive, its attributes, and its rules.
• Phrases, links, and images and frontmatter: the rest of what a page writes.
• Content that varies: writing one page for readers on different platforms or products, with alternatives, availability, and a build for each audience.
• Memos: 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: setting up a glossary, so every page links the terms it uses to their definitions.
• Start pages from templates: 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: 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: linking a guide to an operation in your OpenAPI spec, checked against the spec and written as the operation’s address.
• Editing: the VS Code extension, workspaces with several projects, and other editors.

Check

• Check pull requests in CI: checking every pull request with the same command the editor runs, and the formatting check, in GitHub Actions.
• Check prose with Vale: checking your pages’ prose with Vale, in the editor and in ascribe check.
• Act on the project report: 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: every problem Ascribe reports, with its code and fix.

Review

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

Publish

• Publish a site with Astro: the ways to publish, and publishing a site with @ascribed/astro.
• Deploy the site: building the site in CI and publishing it on GitHub Pages or Netlify, and what each host needs.
• Navigation: 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.
• Search engines and crawlers: what a project tells search engines and AI crawlers about its pages, and what it delivers to agents.
• Keep the addresses you’ve published: recording where a page went when it moves or goes, so a link to its old address still leads somewhere.
• Link to the docs from your product: 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: building the docs of every version a reader can be on from one source, a site for each release line, and moving them on when a line ships.

Agents

• Set up your agent: 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: the content model: page types, dimensions, availability, phrases, widgets, and builds.
• Command reference: every ascribe command, its options, outputs, and exit codes.
• Files Ascribe writes: every file Ascribe puts in a project, and which to commit.
• Element library reference: the custom elements a site draws, and the CSS custom properties that theme them.
• Glossary: 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: the normative contract for the content model file, with the rules a loader enforces and the decisions behind them. The reference above is where to look up a key while 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.
• Navigation: what _ascribe/nav.json holds, the sections and pages in order with their labels, and how a site draws a sidebar from it.
• Archive: what ascribe versions export writes into a folder, and what each page holds.
• JSON reports: the schemas of what the commands write with --format json.
• JSON output: what each page of the json output holds, with its schema.
• The permalinks list: the format of ascribe.permalinks, the list of a project’s permalinks a product can check its links against.
• Tested examples: the formats of ascribe.examples.toml and of the observation ascribe observe writes beside it.
• Site render: the markers the site output writes and how a consumer renders them. The fixtures are in tests/render/.

The Ascribe specification defines the language exactly, for anyone building a tool that reads it. The changelog lists what each release changed.