# Ascribe documentation > Guides and references for writing documentation with Ascribe, and the contracts for implementers. This documentation describes Ascribe 0.4.4. Anything marked in main, not yet released isn't in that release yet. ## Start - [Ascribe documentation](https://ascribed-dev.com/docs/index.md): Guides and references for writing documentation with Ascribe, and the contracts for implementers. - [Getting started](https://ascribed-dev.com/docs/getting-started.md): Install Ascribe, write a first page, check it, build it, see it, and publish it with Astro. - [Bring existing docs to Ascribe](https://ascribed-dev.com/docs/existing-docs.md): Start a project in a folder of Markdown you already have, and take it from ascribe init to a clean ascribe check. - [Install](https://ascribed-dev.com/docs/install.md): Install the ascribe command, in a project with npm, or on your path with Homebrew, the install script, PowerShell, or a release's archive; then start a project with ascribe init. - [Glossary](https://ascribed-dev.com/docs/glossary.md): The terms these docs use, each with a sentence on what it means and a link to the page that documents it. ## Writing pages - [Directive syntax](https://ascribed-dev.com/docs/writing/syntax.md): How a directive is written: its line, attributes, forms, groups, titles, what it applies to, and escapes. - [Directive reference](https://ascribed-dev.com/docs/writing/directives.md): Each built-in directive: what it does, its attributes, and its rules; and project widgets. - [Frontmatter](https://ascribed-dev.com/docs/writing/frontmatter.md): Pages and fragments, and the keys a file's frontmatter takes: the reserved ones, and those its content type declares. - [Phrases, links, and images](https://ascribed-dev.com/docs/writing/inline.md): What a page writes in its prose: phrases, links between files, images, heading ids, and glossary terms. - [Memo files](https://ascribed-dev.com/docs/writing/memo-files.md): A memo longer than a line or two, in a file of its own in memos/: what it's about, where it's placed, and what ascribe check reports. - [Leave a memo for whoever edits next](https://ascribed-dev.com/docs/writing/memos.md): Keeping the reason a page is written the way it is beside it, in the page or in a memo file, for the people and agents who change it, and never for its readers. - [Content that varies](https://ascribed-dev.com/docs/writing/variants.md): Writing one page for readers on different platforms or products, with alternatives, availability, and a build for each audience. ## The content model - [ascribe.toml reference](https://ascribed-dev.com/docs/content-model.md): The content model: what pages are and hold, how content varies, where pages are published, what they draw from, and the checks. - [ascribe.toml: what pages hold](https://ascribed-dev.com/docs/content-model/content.md): The content model's note types, phrases, glossary, images, and widgets: what a page can hold beyond its type's fields. - [ascribe.toml: how content varies](https://ascribed-dev.com/docs/content-model/variation.md): The content model's dimensions, versions and releases, lifecycle states, and features: what content varies along, and how a page says where it applies. - [ascribe.toml: where pages are published](https://ascribed-dev.com/docs/content-model/output.md): How the content model sets the site's consumer, the builds, how pages are listed, what crawlers are told, and where retired permalinks went. - [ascribe.toml: what pages draw from](https://ascribed-dev.com/docs/content-model/sources.md): How the content model names what pages draw from outside the content: the source folders and repositories snippets read, and the OpenAPI specs links point into. - [ascribe.toml: checks and the editor](https://ascribed-dev.com/docs/content-model/checks.md): How the content model sets the checks' levels and the editor's build, what an absent section means, and how the file is validated. - [Set up a glossary](https://ascribed-dev.com/docs/content-model/glossary.md): Write a project's terms on a glossary page, choose which of their occurrences are linked, and keep terms that differ by version or product, so every page links its terms to their definitions. ## Checks and reports - [ascribe check, build, preview, and fmt](https://ascribed-dev.com/docs/checks/check.md): Check a project's sources, build its outputs, preview its pages, and format its Markdown: options, output, and exit codes. - [ascribe report](https://ascribed-dev.com/docs/checks/report-command.md): Report on a project's health, section by section: options, output, and exit codes. - [Diagnostics](https://ascribed-dev.com/docs/checks/diagnostics.md): Every problem Ascribe reports, with its code and fix. - [Diagnostics: content checks](https://ascribed-dev.com/docs/checks/diagnostics/content-checks.md): The checks of a project's pages, which it can set the level of or turn off. - [Diagnostics: content checks across the project](https://ascribed-dev.com/docs/checks/diagnostics/project-checks.md): The checks of a project as a whole, such as orphan pages, what's unused, and release lines, which it can set the level of or turn off. - [Diagnostics: content checks of outputs and the site](https://ascribed-dev.com/docs/checks/diagnostics/output-checks.md): The checks of a project's outputs, prose, external links, published site, and tested examples, which it can set the level of or turn off. - [Diagnostics: directives](https://ascribed-dev.com/docs/checks/diagnostics/directives.md): The diagnostics about attributes, directives, containers, binding, titles, ids, includes, variants, availability, steps, details, and widgets. - [Diagnostics: links and pages](https://ascribed-dev.com/docs/checks/diagnostics/pages.md): The diagnostics about links, images, phrases, headings, frontmatter, and lists. - [Diagnostics: sources, memo files, and navigation](https://ascribed-dev.com/docs/checks/diagnostics/sources.md): The diagnostics about files, snippets, source copies, acknowledgements, permalinks, memo files, navigation, the glossary, and summaries. - [Diagnostics: the addresses file and API specs](https://ascribed-dev.com/docs/checks/diagnostics/project-files.md): The diagnostics about ascribe.addresses, the addresses a base published, and the OpenAPI specs ascribe.toml declares. - [Diagnostics: the content model](https://ascribed-dev.com/docs/checks/diagnostics/content-model.md): The diagnostics about ascribe.toml's file, project, sources, content types, and names, and how to fix each. - [Diagnostics: the content model's builds and site](https://ascribed-dev.com/docs/checks/diagnostics/content-model-builds.md): The diagnostics about releases, phrases, widgets, the consumer, builds, the editor, permalinks, crawlers, listing, and checks in ascribe.toml, and how to fix each. - [The baseline](https://ascribed-dev.com/docs/checks/baseline.md): Put a project's existing advice off for now with ascribe.baseline, so ascribe check reports only what's new: the commands that keep it, and its syntax. - [Check external links](https://ascribed-dev.com/docs/checks/external-links.md): Find the links to other sites that broke or moved, with ascribe report links and lychee, and fix, acknowledge, or leave out each one. - [Checks in CI](https://ascribed-dev.com/docs/checks/ci.md): Check every pull request with the same command the editor runs, and the formatting check, in GitHub Actions. - [Prose, through Vale](https://ascribed-dev.com/docs/checks/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. - [The project report](https://ascribed-dev.com/docs/checks/report.md): Reading ascribe report and acting on each section, from the problems and pages it counts to the external links and the published site, and running it every day in CI. ## Review - [Review](https://ascribed-dev.com/docs/review.md): 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. - [How review works](https://ascribed-dev.com/docs/review/how-it-works.md): What review compares, what its marks mean, how its comments map to the pull request, what it needs from GitHub, and what reaches GitHub. - [Review in the site preview](https://ascribed-dev.com/docs/review/site-preview.md): The Ascribe review app in astro dev's toolbar: its panel, what it compares, its comments, and the pages it has nothing to mark on. - [Attach the HTML preview to every pull request](https://ascribed-dev.com/docs/review/ci-report.md): Write the HTML preview in CI on each pull request, and link it from the run, so anyone can read the change without a checkout. - [ascribe diff and drift](https://ascribed-dev.com/docs/review/diff.md): Compare a project's output with another revision, and find sources that drifted. - [Troubleshooting review](https://ascribed-dev.com/docs/review/troubleshooting.md): What to do when review shows no pull request, no comments, or no marks, says the project has errors, or won't start. ## The editor - [Editing](https://ascribed-dev.com/docs/editor.md): Installing the VS Code extension, which ascribe it runs, and a page for each part of the editor. - [Problems and fixes](https://ascribed-dev.com/docs/editor/problems.md): The problems the VS Code extension shows as you type, the Problems panel and checking every build, their quick fixes, and applying the safe ones. - [Writing in the editor](https://ascribed-dev.com/docs/editor/writing.md): Completion, hover, navigation, renaming, formatting, and highlighting for Ascribe pages in VS Code. - [Actions, new pages, and memos](https://ascribed-dev.com/docs/editor/actions.md): The VS Code extension's actions, which write Ascribe for you, starting a page from its template, and memo files. - [The preview and builds](https://ascribed-dev.com/docs/editor/preview.md): The page preview and the site preview in VS Code, the build you're looking at, and the build lens. - [The sidebar and the status bar](https://ascribed-dev.com/docs/editor/sidebar.md): The Ascribe sidebar in VS Code, with its Project, This page, Pages, and Content model views, the status bar item, and switching the project they show. - [Review in the preview](https://ascribed-dev.com/docs/editor/review.md): Reviewing a change in the VS Code preview: what changed against a base, the Review view, and a pull request's comments. - [Agents in the editor](https://ascribed-dev.com/docs/editor/agents.md): Prompting your agent to fix a problem from VS Code, and the tools and skill an agent in VS Code gets. - [Editor workspaces, settings, tasks, and commands](https://ascribed-dev.com/docs/editor/settings.md): How the VS Code extension handles a workspace with several projects, Project Settings, its tasks, and its settings and commands. - [The language server](https://ascribed-dev.com/docs/editor/language-server.md): ascribe lsp, for an editor other than VS Code: the project a server serves, what it asks of the editor, and the requests of its own. ## Agents - [Agents](https://ascribed-dev.com/docs/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. - [Work with an agent](https://ascribed-dev.com/docs/agents/loop.md): The loop an agent runs on an Ascribe project: edit a page, check it, fix what's reported, and ask the commands that answer what it would otherwise guess. - [Write the agent files](https://ascribed-dev.com/docs/agents/instructions.md): Write your project's rules into the files agents read on their own, AGENTS.md and the Ascribe skill, and keep them current. - [Prompt your agent](https://ascribed-dev.com/docs/agents/prompts.md): Turn a problem, a review comment, or a changed page into a prompt for your agent, in VS Code or from the command line. - [Set up the MCP server](https://ascribed-dev.com/docs/agents/mcp.md): Give an agent with no shell Ascribe's answers as tools, through ascribe mcp. - [Check an agent's edits with hooks](https://ascribed-dev.com/docs/agents/hooks.md): Have Claude Code, Codex, or GitHub Copilot check each file it writes, and the whole project before it finishes. - [Claude Code](https://ascribed-dev.com/docs/agents/claude-code.md): Give Claude Code the skill, the MCP server, the stop hook, the language server, and commands in one install, with the Ascribe plugin. - [GitHub Copilot](https://ascribed-dev.com/docs/agents/copilot.md): Set Ascribe up for GitHub Copilot, in VS Code and as the cloud agent that works on GitHub. - [Index your docs for your product's agents](https://ascribed-dev.com/docs/agents/product-index.md): Write a compact index of your docs into your product's AGENTS.md, so the agents of the people who use your product read them. - [What's sent where](https://ascribed-dev.com/docs/agents/whats-sent.md): What Ascribe sends and to whom when an agent works on your docs, which is nothing, and what your agent reads and passes on. - [What to measure](https://ascribed-dev.com/docs/agents/measuring.md): Where a team sees how search engines and AI agents treat its docs, since Ascribe sees no traffic, and which of the advice about them has evidence behind it. - [ascribe agents and mcp](https://ascribed-dev.com/docs/agents/commands.md): Set a repository up for AI agents, and serve a project's tools over MCP. ## Examples and drift - [Examples and drift](https://ascribed-dev.com/docs/examples.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. - [Show an example from the code](https://ascribed-dev.com/docs/examples/snippets.md): Declare a folder of code as a source, mark a region in a file, and show it on a page with @snippet, so the example changes when the code does. - [Keep the docs in another repository](https://ascribed-dev.com/docs/examples/docs-repository.md): Take code examples from the code's repository when the docs have a repository of their own, pinned to a commit, and keep them up to date with a pull request. - [Report the pages whose examples changed](https://ascribed-dev.com/docs/examples/drift.md): Run ascribe drift on each pull request, so the run's summary lists the pages whose code examples changed while their words didn't. - [Show what an example was tested with](https://ascribed-dev.com/docs/examples/tested.md): Run a folder's tests with ascribe observe, commit what it records, and have each page say what its examples were tested with, and warn when one changed after its last test run. - [ascribe sources and observe](https://ascribed-dev.com/docs/examples/sources.md): Fetch and update the code a project copies from other repositories, and record what tested a folder's examples. ## OpenAPI - [Link to your API reference](https://ascribed-dev.com/docs/openapi.md): Declare your OpenAPI spec in ascribe.toml, link a guide to an operation by its operationId, and have the link checked against the spec and written as the operation's address in Redoc or another renderer. - [Check a JSON example against its schema](https://ascribed-dev.com/docs/openapi/examples.md): Mark a JSON example in a guide as an operation's request or response, and have ascribe check it against that body's schema in the OpenAPI spec, each disagreement at its place in the block. - [Find the operations no guide links to](https://ascribed-dev.com/docs/openapi/coverage.md): See which operations of your OpenAPI spec no page links to, with ascribe check's api-operation-unreferenced and the inventory's count of operations linked for each API. - [Link to an operation with no id](https://ascribed-dev.com/docs/openapi/no-id.md): Link a guide to an OpenAPI operation the spec gives no operationId, by its method and path, which needs Redoc 3, and why setting ids is better. - [Link to operations in the editor](https://ascribed-dev.com/docs/openapi/editor.md): Complete an OpenAPI operation after a link's #, see its method, path, and summary on hover, open it in the spec, and fix a link whose operation was renamed, in VS Code or any editor with the language server. - [Show an operation in a page](https://ascribed-dev.com/docs/openapi/operation.md): Put an OpenAPI operation's method, path, and summary in a guide with @operation, linked to the operation in your API reference and checked against the spec. ## Publishing - [Publishing](https://ascribed-dev.com/docs/publishing.md): What a project tells search engines and AI crawlers about its pages, and what it delivers to agents: listing, robots.txt, the response headers, llms.txt, and the Markdown versions. - [The head, sitemap, robots.txt, and headers](https://ascribed-dev.com/docs/publishing/site.md): What @ascribed/astro writes from the page records for search engines and crawlers: each page's head, the sitemap, robots.txt, and the Markdown versions' response headers. - [Keep the addresses you've published](https://ascribed-dev.com/docs/publishing/redirects.md): Record where a page went when it moves or goes, so a link to its old address still leads somewhere: ascribe.addresses, the check that compares with the base, and the redirects the build writes. ## Publishing with Astro - [Astro](https://ascribed-dev.com/docs/astro.md): Set up an Astro site that publishes an Ascribe project, with @ascribed/astro. - [Put the docs in a site with more than the docs](https://ascribed-dev.com/docs/astro/more-than-docs.md): Serve the docs under a path, such as /docs/, in an Astro site whose home page and other pages are your own or a second Ascribe project. - [Publish for AI agents](https://ascribed-dev.com/docs/astro/agents.md): Publish llms.txt and a Markdown version of each page with an Astro site, so an AI agent reading the docs gets Markdown and an index to choose pages from. - [Serve the Markdown versions](https://ascribed-dev.com/docs/astro/serve-markdown.md): Configure your host to serve the Markdown versions of an Astro site's pages and llms.txt as the Web Documentation Delivery Spec asks, with their type, their response headers, and content negotiation. - [@ascribed/astro reference](https://ascribed-dev.com/docs/astro/reference.md): What the Astro integration takes, what it does to a site, and what it writes for search engines, crawlers, and review. - [Element library reference](https://ascribed-dev.com/docs/astro/elements.md): @ascribed/elements: the custom elements the site output uses, the CSS custom properties that theme them, and styling a project's own note types and lifecycle states. ## Permalinks - [Permalinks](https://ascribed-dev.com/docs/permalinks.md): Link to the docs from your product by permalink, check those links in the product's CI, and keep them working when a section moves, gets a second name, or goes away. - [ascribe permalinks](https://ascribed-dev.com/docs/permalinks/command.md): Keep a project's list of permalinks, check a product's names against it, and retire a permalink with a reason. - [Show the docs in your product](https://ascribed-dev.com/docs/permalinks/in-your-product.md): Show a section of the docs inside your product, in a tooltip, a side panel, or beside an error, by the permalink the product already links to. ## Navigation - [Navigation](https://ascribed-dev.com/docs/navigation.md): 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. - [Put your pages in order](https://ascribed-dev.com/docs/navigation/order.md): Choose the order of a project's sections and pages and their labels, in ascribe.nav or by dragging in the editor. - [Move a site's own list to the navigation](https://ascribed-dev.com/docs/navigation/site-list.md): Replace an Astro site's own list of pages, the src/nav.ts that ascribe init wrote in 0.3, with the project's navigation in ascribe.nav. ## Versions - [Publish a site for each version](https://ascribed-dev.com/docs/versions.md): Build the docs of every version a reader can be on from one source, a site for each release line, and move them on when a line ships. - [Export and retire a line](https://ascribed-dev.com/docs/versions/archive.md): Export a release line to a folder of HTML that needs nothing else, host it, then take the line out of the source and send its addresses on. - [Release lines](https://ascribed-dev.com/docs/versions/lines.md): What a release line is, what each line's output holds and says about itself, how links go between lines, and what a site, the editor, and agents get from them. - [ascribe versions](https://ascribed-dev.com/docs/versions/release.md): List a project's release lines, say what differs between two, release a line in one command, export one into a folder of HTML, and retire it from the source. ## Page templates - [Page templates](https://ascribed-dev.com/docs/templates.md): Starting a page of a known kind, such as a how-to, from a template and a guide to what goes in it, written into your project by ascribe templates eject. - [ascribe templates](https://ascribed-dev.com/docs/templates/command.md): List the page templates Ascribe carries, write them into a project with their content types, and say what's changed in the set since. ## The command - [Command reference](https://ascribed-dev.com/docs/command.md): The ascribe commands: their options, outputs, and exit codes. - [ascribe explain, model, outline, link, refs, rename, resolve, and search](https://ascribed-dev.com/docs/command/questions.md): Ask a project about its diagnostics, content model, pages, links, and references, find where its pages say something, and rename what a page links to. - [A page in the site output](https://ascribed-dev.com/docs/command/site-output.md): What ascribe resolve --emit site writes: a page as the site output gives it to a site, its frontmatter, a line of a versioned build, and how to read its elements without their script. - [Files Ascribe writes](https://ascribed-dev.com/docs/command/project-files.md): Every file Ascribe puts in a project, what writes it, and whether to commit it or leave it to .gitignore. ## For implementers - [ascribe.toml format contract](https://ascribed-dev.com/docs/contracts/content-model.md): The normative contract for the content model file, with the rules a loader enforces. - [ascribe.toml format contract: what pages hold](https://ascribed-dev.com/docs/contracts/content-model/content.md): The normative contract for the content model's note types, phrases, glossary, images, and widgets. - [ascribe.toml format contract: how content varies](https://ascribed-dev.com/docs/contracts/content-model/variation.md): The normative contract for the content model's dimensions, versions and releases, lifecycle states, and features. - [ascribe.toml format contract: where pages are published](https://ascribed-dev.com/docs/contracts/content-model/output.md): The normative contract for the content model's consumer, builds, listing, crawlers, and permalinks. - [ascribe.toml format contract: what pages draw from](https://ascribed-dev.com/docs/contracts/content-model/sources.md): The normative contract for the content model's sources, with ascribe.lock, and APIs. - [ascribe.toml format contract: checks and the editor](https://ascribed-dev.com/docs/contracts/content-model/checks.md): The normative contract for the content model's checks, the editor's build, and defaults. - [ascribe.toml format contract: validation rules](https://ascribed-dev.com/docs/contracts/content-model/validation.md): Every rule a content model loader enforces, and the map of SPEC ยง7.2 to the contract. - [Site-render contract](https://ascribed-dev.com/docs/contracts/site-render.md): The markers the site output writes and how a consumer renders them. - [Output-layout contract](https://ascribed-dev.com/docs/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. - [Asset contract](https://ascribed-dev.com/docs/contracts/assets.md): Where assets go in each output and how pages refer to them. - [Archive contract](https://ascribed-dev.com/docs/contracts/archive.md): What ascribe versions export writes into a folder, how it records what it wrote, and what each page holds. - [Tested examples contract](https://ascribed-dev.com/docs/contracts/tested-examples.md): The formats of ascribe.examples.toml, which says which of a source's files are examples and how to test them, and of the observation ascribe observe writes beside it. - [JSON report contract](https://ascribed-dev.com/docs/contracts/json-reports.md): The JSON Schemas of what the ascribe commands write with --format json. - [JSON reports: ascribe init and ascribe model](https://ascribed-dev.com/docs/contracts/json-reports/model.md): The JSON Schemas of what ascribe init and ascribe model write with --format json. - [JSON reports: ascribe templates](https://ascribed-dev.com/docs/contracts/json-reports/templates.md): The JSON Schemas of what ascribe templates writes with --format json. - [JSON reports: ascribe versions](https://ascribed-dev.com/docs/contracts/json-reports/versions.md): The JSON Schemas of what ascribe versions list, changes, release, export, and retire write with --format json. - [JSON reports: ascribe permalinks and ascribe addresses](https://ascribed-dev.com/docs/contracts/json-reports/addresses.md): The JSON Schemas of what ascribe permalinks and ascribe addresses write with --format json. - [JSON reports: ascribe sources and ascribe observe](https://ascribed-dev.com/docs/contracts/json-reports/sources.md): The JSON Schemas of what ascribe sources and ascribe observe write with --format json. - [JSON reports: ascribe report](https://ascribed-dev.com/docs/contracts/json-reports/report.md): The JSON Schema of what ascribe report writes with --format json. - [JSON reports: ascribe diff and ascribe drift](https://ascribed-dev.com/docs/contracts/json-reports/diff.md): The JSON Schemas of what ascribe diff and ascribe drift write with --format json. - [JSON reports: the commands that answer questions](https://ascribed-dev.com/docs/contracts/json-reports/questions.md): The JSON Schemas of what ascribe explain, outline, link, refs, rename, resolve, and search write with --format json. - [JSON reports: ascribe agents](https://ascribed-dev.com/docs/contracts/json-reports/agents.md): The JSON Schemas of what ascribe agents index, sync, and prompt write with --format json. - [The permalinks list](https://ascribed-dev.com/docs/contracts/permalinks-list.md): The format of ascribe.permalinks, the list of a project's permalinks that something outside the docs can check its links against. - [The navigation contract](https://ascribed-dev.com/docs/contracts/navigation.md): What _ascribe/nav.json in a build's site output holds, the project's sections and pages in order with their labels, and how a site draws a sidebar from it. ## Optional - [Changelog](https://ascribed-dev.com/changelog.md): every release, and what's in `main` not yet released: what changed, and which version a fix is in