Glossary

The terms these docs use, each with a sentence on what it means and a link to the page that documents it.

Each term below is linked from the pages that use it, with its first paragraph as the link’s title. Most of them are ordinary words too, so they’re linked only where a page links them here: acknowledgement, address, agent, build, example, phrase, preview, report, review, source, target, and variant. Each has one meaning in these docs, and where a word is also used another way, its entry says where and what it means there.

Acknowledgement

A note that a problem a check reports is intended, written with @intended beside the content or in ascribe.toml, so the check doesn’t report it again.

Only a check whose next step is review can be acknowledged, and each diagnostic’s entry says where. See @intended.

Address

Where a build publishes a page or its Markdown version, such as /docs/install/, which ascribe.addresses keeps leading somewhere when the page moves or goes.

See Keep the addresses you’ve published. A snippet’s address, such as code:service/client.py#connect, is another thing: the file and region of a source that @snippet shows.

Agent

An AI program, such as Claude Code or GitHub Copilot, that writes a project’s docs with Ascribe’s tools, or reads the docs a site publishes.

Most pages mean the agent you work with on the docs, as Agents does. The outputs for agents, [consumer] agents, and ascribe report delivery are about the agents that read the published site, and ascribe agents index writes for a product’s own agents.

Availability

Where content applies and its lifecycle state there, such as self-managed preview 3.4, written with @available or a page’s available.

See @available. Each build either marks it or removes what isn’t available.

Baseline

The list in ascribe.baseline of the advice a project had when it was written, which ascribe check holds back so it reports only what’s new.

See The baseline.

Build

A named set of choices, in ascribe.toml, for which variants and which availability a page’s output keeps.

Each build is declared in [builds.<name>].

Content model

A project’s schema, ascribe.toml: its content types, dimensions, phrases, and builds.

The content model documents each of its sections.

Dimension

An axis content varies along, such as a package manager or a deployment, declared in ascribe.toml.

See [dimensions] and Content that varies.

Example

Code a page shows from a source’s file with @snippet, so the page has no copy to fall behind, and that ascribe.examples.toml can name so a test runs it.

See Examples and drift and Show what an example was tested with. A JSON block marked as an OpenAPI operation’s request or response is an API example, which the api-example-* checks compare with its schema, and this repository’s examples/ folder holds example projects; neither is this.

Fragment

A source file that exists only to be included in other files: any file with a path segment starting with _, or whose path matches one of the content model’s [fragments] patterns.

See Files and @include.

HTML preview

The HTML file ascribe diff --format html writes, showing a pull request’s changed pages rendered and marked, which CI can attach to the pull request.

It’s the third place to review, beside the page preview and the site preview, and needs no checkout. See Attach the HTML preview to every pull request.

Memo

A note for whoever edits a page next, saying why it’s written the way it is, kept beside what it’s about and never published.

It’s written with @memo in the page, or as a memo file in memos/. See Leave a memo for whoever edits next.

Page preview

The editor’s preview of the active page, rendered as the site shows it.

See the preview.

Permalink

A name for a page or a heading, such as go/weave-config, whose address leads to it wherever it moves, for linking to the docs from outside them.

See Permalinks and @id’s permalinks.

Phrase

A reusable string declared in ascribe.toml and written {key} in a page.

See Phrases.

Preview

Pages shown before they’re published. These docs always say which of the four: the page preview, the site preview, the HTML preview, or ascribe preview.

The page preview is in the editor; the site preview is the project’s own dev server; the HTML preview is a pull request’s, from ascribe diff --format html; and ascribe preview renders a build as a plain site and serves it on this computer with the command alone. None of them is the published site.

Recheck date

When a page is next due to be read against what it describes: its field with the recheck-date role, which recheck-overdue compares with today. It was the review date, with the role review-date and the check review-overdue, and both old names still work for a release.

See Field roles.

Release line

A version of a target as [releases] lists it, such as 3.4, which holds every version that starts with it: live, planned, or archived.

See Release lines. Pages about versions call it a line. Elsewhere a line is a file’s line, and a code block’s tested line is the line under it that says what it was tested with.

Report

What ascribe report says about the state of a whole project: its problems, inventory, builds, pages, external links, and published site.

See The project report. The HTML preview, which ascribe diff --format html writes for a pull request, is part of review, not this.

Review

Reading a pull request’s changes as readers will see the pages, in the page preview, the site preview, or the HTML preview, and commenting there.

See Review. A diagnostic whose next step is review may be fine as it is: see What to do next. When to check a page again is its recheck date, not a review.

Site preview

The active page on the project’s own dev server, in the browser or the preview panel. It has the published site’s look, where ascribe preview has the element library’s.

See the site preview.

Source

A folder or repository outside the content, declared in [sources.<name>], that pages take code examples from with @snippet.

See [sources.<name>] and ascribe sources. A page’s source file, the Markdown it’s written in, is the ordinary sense: a source file, as against what a build writes from it.

Target

A dimension value that availability names, such as self-managed in self-managed preview 3.4; a versioned one has release lines, which [releases.<target>] lists.

See Availability specs and [releases.<target>]. A link’s target, as ascribe link, refs, and rename take it, is what the link leads to, and ascribe agents sync --target names an agent whose files it writes.

Variant

Alternative content for a value of a dimension, written with @variant.

See @variant and Content that varies.