DocsWhy AscribeGitHub

Ascribe documentation

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

For AI agents: the documentation index is at llms.txt, and this page is available as Markdown.

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.

For engineers

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

  1. Checks 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. Phrases and includes: write a name or a passage once, and use it 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. Review in the preview: 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: 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.
  • Install: 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.
  • Page 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

  • Checks in CI: checking every pull request with the same command the editor runs, and the formatting check, in GitHub Actions.
  • Prose, through Vale: checking your pages’ prose with Vale, in the editor and in ascribe check.
  • 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

Publish

  • Astro: publishing a site with @ascribed/astro.
  • 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.
  • Publishing: 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.
  • Permalinks: 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

  • Agents: 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

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.
  • 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 is the normative definition of the language. The changelog lists what each release changed.