Repository navigation
supdoc v0.3.0
supdoc v0.3.0 adds code blocks: it checks the fenced code in your Markdown and in Rust doc comments, keeps excerpts in sync with the code they quote, and formats and lints blocks with your project's own tools. Linking works as before, and the lockfile keeps schema_version = 2.
Code blocks
Turn the feature on with a [features.code-blocks] table, and each language with its own table: [features.code-blocks.rust], .shell or .python. A block in a language without a table is counted as not checked. [features.code-blocks] has its own include and exclude, which default to the top-level ones, so you can link everywhere and check code only in, say, docs/ and skills/.
- Excerpts that can't drift.
```rust from(src/lib.rs#Limits.resolve)makes a block exactly that symbol's text. You can repeatfrom(...); the excerpts are joined in order by a blank line. A stale block iscode-block-stale, andsupdoc fixrewrites it. - Hand-written blocks you want to keep honest.
uses(PATH#SYMBOL)tracks a symbol like a link, in any language.supdoc checkflags the block for review when the symbol changes, andsupdoc updaterecords the change. - Formatting with rustfmt (under your pinned toolchain and edition), shfmt (with your shell dialect), and ruff format or black. Unformatted blocks are
code-block-unformatted, andsupdoc fixapplies the formatter's output. Output that would close the fence or edit outside the block is refused. - Linting with ruff check for Python and shellcheck for shell. Each finding is
code-block-lintat the doc's own line and column. - Explicit switches, never automatic. supdoc never rewrites a block behind your back or invents a skip.
- Per block:
ignore(<reason>),lint(off: <reason>),format(off: <reason>), orlint(full)/format(full)to override the config. - Per tool:
[features.code-blocks.<language>.<tool>] lint/format = "full" | "off". - A step that didn't run is always counted and named, for example "1 lint not run (clippy needs trust)".
- Per block:
- Safe on untrusted docs. Tools are found on
PATH, never inside the checkout. Each one runs in its own process group, from an empty private directory, with a cleared environment, the block on stdin, capped output and a per-block timeout ([limits] code-block-timeout). Ctrl-C or SIGTERM stops every tool, and supdoc then ends by that signal. - Fast. Results are cached outside the checkout, and distinct blocks run in parallel.
Not in this release
- Clippy for Rust blocks is built, but it runs only in the project tier, which arrives with
supdoc trust. Compiling an untrusted block needs an OS-level file sandbox first. Until then, a Rust block's lint step reads "not run (clippy needs trust)". - rustdoc-style hidden
#lines aren't supported: a#line is ordinary code. Write context visibly, or excerpt it withfrom(...).
New codes
code-block-stale,-source-missing,-uses-new,-uses-changed,-uses-obsolete;code-block-unformatted,-parse,-lint;code-block-tool-missing,-tool-failed,-tool-timeout;code-block-not-checked,-unknown-attribute,-missing-reason,-fix-unsafe.
Every one has a help that names a command or value.