Diagnostics

Every problem Ascribe reports, with its code and fix.

Every problem Ascribe reports, with its code, its name, and how to fix it. ascribe check, ascribe build, and the editor report the same diagnostics, with the same codes.

A problem is what Ascribe found in your project, at one place. A diagnostic is the kind of problem, with a code, that this page and ascribe explain describe. In the messages below, {name} stands for a value filled in from your source.

The diagnostics are on nine pages, by what they’re about:

• Directives: attributes, directives and their containers, binding, titles, ids, includes, variants, availability, steps, details, and widgets.
• Links and pages: links, images, phrases, headings, frontmatter, and lists.
• Sources, memo files, and navigation: files, snippets, source copies, acknowledgements, permalinks, memo files, navigation, the glossary, and summaries.
• The addresses file and API specs: ascribe.addresses, the addresses a base published, and the specs [apis] declares.
• The content model: ascribe.toml: the file, [project], [sources], content types, and names.
• The content model’s builds and site: the rest of ascribe.toml: [releases], phrases, widgets, the consumer, builds, the editor, [permalinks], [crawlers], [listing], and [checks].
• Content checks: the content’s quality, which a project can set the level of: the checks of pages.
• Content checks across the project: the checks of the project as a whole, such as orphan pages and what’s unused.
• Content checks of outputs and the site: the rest of the content checks: outputs, prose through Vale, external links, the published site, and tested examples.

Each entry ends with the section of the directive reference, directive syntax, frontmatter, phrases, links, and images, or the ascribe.toml reference about what it checks, which has examples, and links to its part of the specification.

In the editor, many diagnostics offer a quick fix. See Quick fixes.

Each entry opens with a line such as “Advice · page level · next step: write · configurable in [checks]”: the diagnostic’s severity, its level, its next step, whether a project can set its level, and, for a check whose problems can be acknowledged, where. It ends with the diagnostic’s section of the specification.

Severity

An error, a warning, and advice are how severe a problem is.

• An error makes ascribe check fail, and stops ascribe build from writing anything. A diagnostic about ascribe.toml (a name that starts with model-) stops everything else when it’s an error: every other check depends on the content model.
• A warning doesn’t, unless you pass --deny-warnings.
• Advice never does, even with --deny-warnings: ascribe check lists it after the errors and warnings and counts it apart, and the editor shows it as information.

A check that’s off by default reports nothing until a project names it in [checks]: see Setting a check’s level.

File level and page level

A file-level diagnostic is about one file on its own. A page-level diagnostic is about a page after its includes are expanded and a build’s modes are applied, so it can depend on the build; the message names the builds it appears in.

What to do next

Each diagnostic says what kind of next step it has. ascribe check --format json gives it as next, and the editor in each diagnostic’s data, so a tool or an agent can offer the right thing.

Setting a check’s level

A check about the content’s quality, rather than whether the project is valid, can be set to another level, or turned off, in [checks] in ascribe.toml. Those checks are listed under Content checks, Content checks across the project, and Content checks of outputs and the site, and their entries say they’re configurable. Every other diagnostic is about whether the project is valid, which a project can’t lower or turn off.

A few content checks matter only to some projects, and are off unless [checks] names them; their entries say they’re off by default. Name one with a level to turn it on at that level, or with a table of its settings to turn it on at the level its entry gives. summary-missing and summary-long, for a project that shows its docs in a product, are turned on like this:

[checks]
summary-missing = "advice"
summary-long = "advice"

Index