outlint
Lint the header structure (outline) of Markdown documents against a declarative schema.
This is a 0.x release: expect breaking changes to the CLI surface, the
schema language, and the JSON output before 1.0. The normative
specification is
spec/outlint-spec.md;
where the two disagree, the specification wins.
Install
This builds the check-only edition. Use cargo install outlint --locked --all-features
for all commands, including search and read. GitHub Releases also provide
outlint-<target> check-only archives and outlint-full-<target> full archives,
with separate shell and PowerShell installers. Both editions install an
executable named outlint.
Example
.outlint.yml:
version: 1
title: "*" # exactly one h1, any text
sections: # rules for h2 headings, in document order
- id: overview
match: "Overview"
required: true
- id: design
match: "Design"
required: true
sections: # this declared child scope is exhaustive
- match: "Alternatives"
- id: rollout
match: "Rollout"
required: false
design.md:
design.md:1:1 [missing-section] matched 0 sections, but at least 1 are required
expected: "Design"
rule: .outlint.yml:7:5
design.md:3:1 [misplaced-section] the section matches a rule but cannot occupy its ordered phase
section: "Widget Redesign > Design"
schema: .outlint.yml:2:8
2 diagnostics in 1 file
This example shows the current human presentation only. It is not a stable or
parseable output grammar; use --format json for scripts and integrations.
Schemas may also declare an exhaustive ordered content sequence for the
visible direct blocks in a root or heading preamble and, on an outer list
rule, an items sequence for that list's direct syntactic items. Block rules
match p, list, or any; one_of is one non-nesting choice phase with at
least two block matcher alternatives. Omission means “do not validate this
scope”; content: [] and items: [] instead validate it as empty. Item text
exists only when the first direct block is a paragraph (tight or loose); a
no-text item matches only the wildcard, while present-empty text is ordinary
text (an exact empty matcher can match it).
Ownership is direct-only. Frontmatter, link-reference definitions, and
complete CommonMark HTML comments surrounded only by CommonMark ASCII
whitespace are transparent; other visible block kinds participate. Explicit
content/item ids share and hoist through the structural namespace. Locators
can move from names to indexed /p, /list, and /item steps, never back to
names. Provisional item /text is schema-resident only immediately after a
named exact/glob/regex item rule that is statically singular or narrowed by
[i]; it is not accepted after /item or a wildcard and creates no
proposition.
outlint-disable immediately before a heading, visible block, or direct item
filters diagnostics anchored to that node. Absence and too-few findings can be
disabled only file-wide; outlint-disable-file covers the whole document.
Filtering never changes matching or dependency state.
This surface keeps schema version 1 and envelope version 2. Deferred syntax has no semantics: correspondence/selection, paragraph/lead text, link definitions, editing and concrete edit paths, task state, matchable quote/code/HTML/break/table predicates and GFM tables, nested item/cell validation, item captures/order, content/item guards/extras/unordered scopes/phases/constraints, meaningful-item predicates, equal/subset value constraints and selection objects, sequence contiguity, capture-cardinality refinements/optional participation, integer coercion/rounding, and numbering.
Without --schema, each input file discovers its schema by walking up:
<stem>.outlint.yml (its file name, extension removed) is preferred over
.outlint.yml in each directory.
--format json emits a versioned, machine-readable object on stdout. For a
rollout.md that has # Widget Redesign, ## Overview, and ## Rollout
but no ## Design:
The envelope is version 2. The number changes only at a release. Before
release 1.0 the shape may change incompatibly under the same number, so
consumers pin the outlint release rather than trust a matching number alone.
From 1.0 onward the number is a compatibility promise: a consumer must read
version and reject a number it does not understand rather than assume the
older reference shape. There is no compatibility mode.
Every diagnostic carries a target object tagged by kind: header,
missing_header, document, or frontmatter. They stay distinct because
the text they carry has different provenance — a missing_header matcher is
schema text that may occur nowhere in the document.
Where a diagnostic names the schema locators it evaluated, it also carries
references. Each entry is tagged by kind and keeps the locator's
original spelling in locator:
rule—anchor(current_scopeorschema_root), thepathof declared names, an optionalpositionsarray aligned withpathgiving each step's[i]or null, and the rule'smatcher. Position values are JSON integers of arbitrary size and must not be assumed to fit 64 bits.frontmatter_query— thequeryinsidefm[...]without the wrapper, plus anequalsobject oftypeandvaluewhen the locator spelled an equality literal.frontmatter_capture— the capture'snameand its declaredtype.
Typed Values diagnostics are located in the schema through schema_node,
which adds the capture, frontmatter_capture, and order_entry kinds to
the existing ones. Section 11.3 of the specification is the normative shape;
every member listed there appears only when the corresponding semantic data
exists.
In human output, an invalid-value names the responsible capture or
frontmatter query and the type that was expected, and an order-violation
names the capture, the declared direction, and both values of the offending
adjacent pair. As with all human output, that wording is presentation and
may change between releases; parse --format json instead.
Schemas can be checked on their own:
Commands and options
Run outlint --help for the command summary, or the help option on either
validation command for its complete flags:
Usage: outlint <command> [options]
Commands:
check Validate Markdown documents
schema check Validate Outlint schema files
Options:
-h, --help Show help
-V, --version Show version
outlint check --help:
Usage: outlint check <FILE>... [options]
Validate individual Markdown files. Without --schema, each file discovers its
schema separately: the nearest <stem>.outlint.yml (file name, extension
removed) or .outlint.yml, specific name first in each ancestor directory.
Standard input (-) requires --schema.
Options:
-s, --schema <SCHEMA> Use one schema for every input
--format human|json Select output format (default: human)
--color auto|always|never
Control human-output color (default: auto)
-h, --help Show help
Exit codes: 0 valid, 1 validation diagnostics, 2 usage or operational error.
outlint schema check --help:
Usage: outlint schema check <SCHEMA>... [options]
Validate schema syntax, normalization, ids, matchers, cardinalities, constraints,
and all other schema-load-time checks.
Options:
--format human|json Select output format (default: human)
--color auto|always|never
Control human-output color (default: auto)
-h, --help Show help
Exit codes: 0 valid, 1 validation diagnostics, 2 usage or operational error.
outlint --version (or -V) prints the package version. The version option
is top-level; the validation subcommands accept --help but not --version.
Input and schema selection
outlint check accepts one or more individual Markdown file paths. Without
--schema, it searches upward from each file, checking each ancestor
directory first for <stem>.outlint.yml — the file's name with its final
extension removed, so CHANGELOG.md discovers CHANGELOG.outlint.yml —
and then for .outlint.yml; the nearest match wins, and files in one
invocation may use different schemas. Other schema filenames are never
discovered automatically. -s, --schema <SCHEMA> selects one schema for
every input and disables discovery.
The file path - reads standard input and requires an explicit --schema.
Outlint never reads stdin merely because no file was supplied. Directories
are not traversed; expand them with your shell or find.
outlint schema check accepts one or more schema paths and performs all
load-time checks, including linked frontmatter JSON Schema loading, without
checking a Markdown document.
Both commands require UTF-8 input. A leading UTF-8 byte-order mark is
accepted. The argument -- ends option parsing, allowing a later path to
begin with -.
Output options
--format human|json selects reader-oriented diagnostics or one versioned
JSON object for the invocation. Human output is the default and is quiet on
success. Its wording, layout, and ordering may change between releases and
must not be parsed as machine input. JSON is the specified machine-readable
interface and is always written without ANSI escapes.
--color auto|always|never controls ANSI color in human output. auto, the
default, enables it only when standard output is a terminal; always forces
it and never disables it. This option does not add color to JSON.
JSON results follow input order. Within a JSON result, diagnostics have a fixed total order beginning with source line, byte column, diagnostic id, schema location, and target. See specification Section 11.4 for the complete key. Human output may order or group diagnostics differently for readability.
Validation output goes to stdout. Usage errors and failures to read or locate
inputs go to stderr. If both diagnostics and an operational error occur,
Outlint reports both and exits with status 2. A frontmatter fm[...] query
whose result cannot be evaluated in full is such an operational error, not a
diagnostic: the document has no verdict, and Outlint reports that rather than
a partial diagnostic set that would read like a cleaner document than it is.
Exit codes
| Code | Meaning |
|---|---|
0 |
All checked documents and schemas are valid |
1 |
Validation completed and at least one diagnostic was emitted |
2 |
An invocation or operational failure prevented normal validation |
Related
outlint-core— the pure, IO-free library this tool is built on.- Outlint specification, Section 11 — the normative behavior contract. This README describes how to use the reference CLI; help layout and every aspect of human formatting are presentation, not a portable or machine-readable contract.
License
Licensed under either of Apache License, Version 2.0 or MIT license at your
option (MIT OR Apache-2.0).