Skip to content

Releases

supdoc v0.6.0

Choose a tag to compare

@github-actions github-actions released this 11 Nov 17:38
Immutable release. Only release title and notes can be modified.
110d71b

supdoc v0.6.0 checks code blocks in SQL, HTML, Makefile and XML end to end, and adds npm packages that carry the release binaries. The lockfile format is unchanged. What shipped is in the v0.6.0 milestone.

Install

  • From v0.6.0 on, npx supdoc runs supdoc and npm i -g supdoc installs it. The supdoc package pulls in one @supdoc/<os>-<cpu> package holding the release binary for macOS, Linux (statically linked) or Windows, on x64 or arm64. Nothing is compiled and no install script runs (#402).
  • supdoc upgrade refuses a binary that an npm package installed and prints the npm command to run instead, so it never rewrites a file inside node_modules.

More code-block languages

Each language is turned on by its own table, such as [features.code-blocks.xml].

  • SQL blocks are now linted with sqruff as well as formatted. An unparsable block fails, and a noqa comment can't hide a parse error (#437).
  • HTML blocks are now linted with biome as well as formatted with superhtml (#436).
  • Makefile blocks (tagged make, makefile, Makefile or mk) are formatted with mbake and linted with checkmake. supdoc never asks mbake to validate, which would run make, and always passes each tool a vetted copy of the project's config (#439).
  • XML blocks (tagged xml, svg, xsd, xsl, xslt or xhtml) are linted and formatted with xmllint, without network access or catalogs. A block whose DOCTYPE names an external identifier or that declares an entity is left unchecked with a warning (#440).

Also

  • The remaining code-block read guards refuse a root that can't be resolved, and tests pin it (#454).

Full changelog: v0.5.0...v0.6.0

v0.5.0

Choose a tag to compare

@github-actions github-actions released this 10 Nov 21:26
Immutable release. Only release title and notes can be modified.
f567032

supdoc v0.5.0 ships prebuilt binaries for eight targets, builds and runs on Windows, and checks code blocks in four more languages. The lockfile format is unchanged. The JSON output of supdoc upgrade gains fields; nothing is removed. Most of what shipped is in the v0.5.0 milestone; SQL and HTML formatting are the first parts of #437 and #436, which stay open for v0.6.0.

Upgrading

  • A v0.4.0 release binary can't upgrade itself. supdoc upgrade for a downloaded binary starts at v0.5.0, so download the v0.5.0 archive by hand once. A cargo install upgrades through cargo as before (#370).

Install

  • Each release carries prebuilt archives for eight targets: macOS (arm64, x86_64), Linux (arm64, x86_64, each glibc and musl) and Windows (x86_64, arm64), with a SHA256SUMS file and build attestations (#368).
  • cargo binstall supdoc installs the prebuilt binary (#405).
  • From v0.5.0 on, releases are immutable: a published release's assets can't be replaced (#403).
  • supdoc upgrade [VERSION] now also upgrades a downloaded release binary. It fetches the archive with the system curl over HTTPS from GitHub, checks it against SHA256SUMS, and replaces the binary in place; on Windows the old one is left as supdoc.exe.old, which a later upgrade removes. A cargo install still upgrades through cargo, except on Windows, where upgrade prints the cargo command to run from another shell. Any other install is refused with the manual step. Without --yes it only previews (#370, #431).
  • supdoc upgrade --json gains method (cargo or release-binary), asset, sha256 and notes.

Windows

  • supdoc builds and its test suite passes on Windows x86_64 and arm64, and both are required CI checks. The trust store and the code-block cache live under %LOCALAPPDATA%\supdoc (#369).

More code-block languages

Each language is turned on by its own table, such as [features.code-blocks.sql].

  • CSS and SCSS blocks are formatted and linted with biome (#441).
  • Dockerfile blocks (also tagged containerfile) are linted with hadolint and formatted with dockerfmt (#438).
  • SQL blocks are formatted with sqruff. dialect in [features.code-blocks.sql] picks the dialect (ansi by default), and a block tagged with a dialect, such as postgres or tsql, uses it whatever the setting says. There is no built-in SQL linter yet (#437).
  • HTML blocks are formatted with superhtml. A block holding a <textarea>, <xmp>, <listing>, <plaintext> or <noscript>, or a <script> or <style> whose body superhtml would rewrite, is left unformatted with a warning. There is no built-in HTML linter yet (#436).
  • linter = "markdownlint-cli2" in [features.code-blocks.markdown] is refused with an explanation: markdownlint-cli2 can't apply its per-directory config to a block passed on stdin. Use rumdl or a custom linter = { command = [...] } (#325).

Also

  • supdoc skill install --target agents or --target claude writes only that one skill copy (#401).
  • TypeScript, TSX and JavaScript get symbols for the keys of a default-exported object (#404), and for a namespace A.B.C.D of four to ten parts (#249).
  • supdoc init works on a filesystem without hard links (#250).
  • check, update, fix and list check a path as typed: nope/.. exits 2 with cli-path-missing when nope doesn't exist, instead of checking the whole project, and so does file.md/.. (#248).
  • The link-outside-root help for a namespace link that climbs out of its namespace no longer suggests moving the config (#251).
  • Code-block read guards use one shared containment check (#371), and raw path joins outside the path module fail clippy in CI (#357).

Full changelog: v0.4.0...v0.5.0

supdoc v0.4.0

Choose a tag to compare

@aidenzepp aidenzepp released this 05 Nov 20:07
3eabd1a

supdoc v0.4.0 adds trust, code-block checking for seven more languages, links to keys in JSON, YAML and TOML files, and supdoc upgrade. The lockfile format is unchanged. The JSON output gains fields and two new commands' schemas; nothing is removed. Everything shipped is in the v0.4.0 milestone.

Upgrading

  • Links into JSON, YAML and TOML files become tracked. They were left untracked before. Each one shows as link-new until it is recorded, so run supdoc update --yes once after upgrading, or check fails (#245).
  • A checkout's [limits] can't raise a ceiling unless you trust it. A raise or 0 in an untrusted checkout is held back, and supdoc config show says so. The flag and environment variable always win (#348).
  • from(...) or uses(...) starting with // is refused as climbing out of the project, like any path outside the root (#350).

Trust

  • supdoc trust records that a checkout may run tools that load its own code; --revoke removes it, and SUPDOC_TRUST=1 grants it for one run. No file in the checkout can grant it (#237).
  • In a trusted checkout, clippy lints Rust blocks against the project's build (#238). pylint (Python), prettier (TypeScript, JavaScript, JSON, YAML and Markdown) and eslint (TypeScript and JavaScript) can be selected in a language's table; they run only in a trusted checkout and are found in the project's .venv/bin or node_modules/.bin first (#239).
  • Custom formatter and linter commands: formatter = { command = [...] } and linter = { command = [...], diagnostics = "gnu" } run only in a trusted checkout (#240).

More code-block languages

  • TypeScript and JavaScript (biome), Go (gofmt, go vet in a module supdoc owns), Markdown (rumdl), JSON (biome), YAML (yamlfmt, yamllint) and TOML (tombi, offline) blocks are formatted and linted without trust (#242, #243, #244, #246).
  • Code blocks in Python docstrings, JSDoc and TSDoc comments (including a fenceless @example) and Go doc comments are checked (#247).
  • fragment(<kind>) marks a block that shows statements, an expression, object entries or JSX children, and its tools check it in a fixed frame instead of failing to parse (#281).

Links to data files

  • A link can name one key: [version](Cargo.toml#package.version), [test job](.github/workflows/ci.yml#jobs.test). Arrays use 0-based indices; a . or ~ in a key is written ~1 or ~0. [limits] max-key-segments bounds a hostile file (#245).

supdoc upgrade

  • supdoc upgrade [VERSION] reinstalls supdoc through cargo install --locked, showing the plan first and acting only with --yes. It works for cargo installs only (#241).

Hardening

  • Every path supdoc builds from file content (the lockfile, config, doc links, from(...)/uses(...), git metadata, tool configs and output) goes through a validated type, and every write, rename or delete is checked for containment just before it happens (#336).
  • [limits] max-file-size caps every file supdoc reads (#296).

Also

  • The README is rewritten as a front page; detail moved to each command's --help (#299).
  • Tests that depended on machine speed no longer fail under load (#322).

Full changelog: v0.3.1...v0.4.0

Binaries (added 2026-11-06). macOS and Linux archives built from this tag by the release workflow are attached, with SHA256SUMS and build-provenance attestations (gh attestation verify <archive> -R aidenzepp/supdoc). Windows binaries, and supdoc upgrade for a downloaded binary, start at v0.5.0, so a v0.4.0 binary is upgraded by downloading a newer one.

supdoc v0.3.1

Choose a tag to compare

@aidenzepp aidenzepp released this 04 Nov 16:39
b3277d2

supdoc v0.3.1 fixes two things in v0.3.0's code blocks: the summary of steps that didn't run, and the README's description of which tools run. Output schema, lockfile and config are unchanged.

Fixed

  • Each not-run reason gets its own count. v0.3.0 gave every step that didn't run one label, so a project with one missing shell tool read "62 lint not run (tool missing)" when 57 of those Rust blocks were waiting on supdoc trust. The summary now lists each reason with its own count, for example "57 lint not run (clippy needs trust) · 5 lint not run (tool missing)" (#227).
  • The README no longer says clippy runs. clippy is built, but it runs only in the project tier, which arrives with supdoc trust. Until then a Rust block's lint step counts as not run. The README now lists only the tools that run: rustfmt, shfmt, ruff, black and shellcheck (#225).

Also

  • supdoc now checks the code blocks in its own vendored skills (#226).

supdoc v0.3.0

Choose a tag to compare

@aidenzepp aidenzepp released this 04 Nov 14:17
29196fd

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 repeat from(...); the excerpts are joined in order by a blank line. A stale block is code-block-stale, and supdoc fix rewrites it.
  • Hand-written blocks you want to keep honest. uses(PATH#SYMBOL) tracks a symbol like a link, in any language. supdoc check flags the block for review when the symbol changes, and supdoc update records 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, and supdoc fix applies 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-lint at 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>), or lint(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)".
  • 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 with from(...).

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.

Also fixed

  • A termination signal always ends supdoc by that signal: no output after it, and no tool left running (#208, #210).

supdoc v0.2.1

Choose a tag to compare

@aidenzepp aidenzepp released this 03 Nov 17:24
1b8e1d0

supdoc v0.2.1 makes check faster by compiling each language only when a file of that language is read. Output, the lockfile and the JSON schema are unchanged from v0.2.0.

Faster

Before, every run compiled the queries for every built-in language at startup. Now each language compiles the first time a file of that language is read, at most once per run (#177).

Median check --quiet on an Apple M4 Pro, measured with hyperfine:

project v0.1.2 v0.2.0 v0.2.1
ripgrep 247.5 ms 290.1 ms 241.7 ms
supdoc 218.1 ms 237.1 ms 217.8 ms

This recovers the startup cost v0.2.0 added and keeps its lower memory use. check --json output is byte-identical to v0.2.0 on both projects.

Changed

  • A built-in language whose query fails to compile still fails the run with read-cartridge-load (exit 70) and the same help. It now happens when a file of that language is read, in any command that reads files, rather than on every run. CI still compiles every built-in, so a broken query can't ship.

supdoc v0.2.0

Choose a tag to compare

@aidenzepp aidenzepp released this 02 Nov 05:53
6d47024

supdoc v0.2.0 is a breaking release. The JSON output schema moves to schema_version 2, the Rust library is no longer a public API, and several defaults change. Your supdoc.config.toml and supdoc.lock keep working, but some lock keys re-key once (see "Re-keys once" below): run supdoc update --yes after upgrading.

Breaking changes

  • JSON schema version 2 (#169, #167, #138).
    • config show --json: line_endings.file is now line_endings.from, and each limits.*.file is limits.*.from.
    • The nine per-command cli-*-output codes (cli-check-output, cli-config-output, cli-fix-output, cli-list-output, cli-namespace-output, cli-rename-output, cli-resolve-output, cli-skill-output, cli-update-output) and init's report failure are now one code, cli-output-failed. cli-init-write now means only that the config file could not be written.
    • --jsonl: the summary line now carries exactly the fields --json has. The flat keys are gone: read summary.* instead of the flat link counts, and settings_change.line_endings.{from,to} instead of line_endings_from and line_endings_to.
    • config show --json gains a limits object.
  • The library is no longer a public API (#173). The supdoc crate exposes only the binary's entry point and a documented supdoc::testing module for its own integration tests. Use the CLI and its JSON output.
  • Config discovery stops at the top of the git work tree (#155). A submodule or nested repository without its own supdoc.config.toml no longer uses the superproject's config. Pass -c PATH to use it.
  • init refuses inside a configured project (#154): cli-init-nested, exit 2, naming the config it found. Use supdoc init -c ./supdoc.config.toml to write a nested one on purpose.
  • Every PATH argument is checked (#146). supdoc check . nope.md now refuses nope.md (exit 2) instead of checking the whole project.
  • Config patterns refuse . segments (#134). include = ["./docs"] matched nothing before; it is now a config-parse error (exit 78) that says to write docs.
  • Removed: the unreachable code cli-rename-invalid-source-path (#164).

Limits for hostile or generated files

A new [limits] table, with matching environment variables and global flags (#138, #153, #160, #161, #170). Precedence is flag, then environment, then config, then the default. 0 means no limit, and every value needs a unit.

limit default config key env flag refusal
per-read parse and query time 10s parse-timeout SUPDOC_PARSE_TIMEOUT --parse-timeout read-timeout, exit 1
lockfile size 16MiB max-lock-size SUPDOC_MAX_LOCK_SIZE --max-lock-size lock-too-large, exit 78
config file size 256KiB env and flag only SUPDOC_MAX_CONFIG_SIZE --max-config-size config-too-large, exit 78
ignore file size 256KiB max-ignore-size SUPDOC_MAX_IGNORE_SIZE --max-ignore-size ignore-too-large, exit 78
  • One deadline covers each read's parse and every query over it. A timed-out file is never left half-read, and every command exits 1 and prints the finding.
  • The size caps are checked on the open file before anything is read, and a file that grows while it is read is still refused.
  • A config file can raise its own limits. In CI, set the SUPDOC_* variables or flags so a pull request can't loosen them.

Re-keys once

These change which links supdoc tracks or how a symbol is named, so update --yes re-records the affected entries once:

  • Markdown anchors match GitHub (#148). Slugs keep combining marks and connector punctuation, and headings inside quotes and lists count toward -1, -2 numbering.
  • Accessor pairs and overloads are one symbol (#145, #149). A getter and setter, a Python property and its setter, or TypeScript overload signatures with their implementation resolve to one symbol instead of being ambiguous. Ambiguity lists show five candidates, then a count.
  • One TypeScript query for .ts and .tsx (#149). Dotted namespaces, export var, private names and object-literal members name the same way in both.
  • Doc links supdoc doesn't track (#140). A link to a directory, or a #fragment link to a file type no language reads, is left untracked instead of being an error. check -v counts them.

Safer by default

  • A supdoc.config.toml or supdoc.lock that is a symlink is written through to its real file inside the project, and refused when the real file is outside it (#141).
  • A link target that isn't a regular file (a FIFO, socket or directory) is refused with read-not-a-file instead of hanging (#159).
  • Non-regular lockfiles and extends targets are refused (#89, #113).
  • namespace rename refuses before writing anything when an ignore file is over its limit, and rewrites every link written with the old prefix, tracked or not (#156, #161).
  • The global git excludes file is found once and capped like other ignore files (#170).

Correctness

  • A path-scoped check or update sees links that moved from a source that no longer exists (#142).
  • fix repairs //, \ and :~: links when the repair is unique (#150), and a source deleted mid-fix is reported as changed (#144).
  • A closed stdout keeps the run's exit code (#135, #175).
  • A built-in language that fails to load fails the run (read-cartridge-load, exit 70) instead of reading nothing (#136).
  • Hash settings travel with the lock, and out-of-range symbols fail closed (#83).

Clearer messages

  • Unreadable ignore files warn (scan-ignore-file-unreadable), and an ignored path's help names the file holding the rule (#152).
  • A named path in a skipped directory or an unread file type warns, and a path the walk never reached says so (scan-explicit-path-unscanned) (#139, #152).
  • Every printed command keeps your -c and arguments (#91, #117, #125, #175).
  • Every error and warning help names a command or value to try, enforced by a test gate (#97, #119).
  • Unsupported-language and extensionless files say what to do (#163).

Faster and smaller

  • Peak memory of check drops sharply because trees are dropped once their links are read (#131): rust-analyzer 421.0 to 32.6 MiB, ripgrep 88 to 31 MiB, supdoc 82 to 22 MiB.
  • Wall time is slightly slower than v0.1.2. Median check --quiet on an Apple M4 Pro: ripgrep 247.5 to 288.1 ms, supdoc 218.1 to 237.0 ms, rust-analyzer about 2 to 6% slower. A profile puts about half of it on compiling the larger TypeScript queries at startup, and half on re-parsing a doc that is also a link target, which is the price of the memory drop. Compiling each language only when a file of that type is first read is the planned fix.

New codes

cli-init-nested, cli-output-failed, cli-rename-config-outside-root, config-too-large, ignore-too-large, lock-too-large, read-cartridge-load, read-not-a-file, read-timeout, scan-explicit-path-unscanned, scan-ignore-file-unreadable.

Removed codes

cli-check-output, cli-config-output, cli-fix-output, cli-list-output, cli-namespace-output, cli-rename-output, cli-resolve-output, cli-skill-output, cli-update-output (now cli-output-failed), and cli-rename-invalid-source-path.

supdoc v0.1.2

Choose a tag to compare

@aidenzepp aidenzepp released this 01 Nov 17:18
c8abc9d

supdoc v0.1.2 is a fix release. Nothing in the lockfile format or the config schema changes, so v0.1.1 projects work unchanged.

Faster

supdoc check on a project with 20,000 links drops from 10.9 s to 1.6 s (6.8x), measured with hyperfine on the same project and machine. Output is unchanged.

  • Lock parsing and finding locations no longer count newlines from the start of the file for every link (#70).
  • A comment region with no [ is no longer parsed for links (#65).

Stays inside the project

  • list TARGET#symbol no longer reads outside the project root, and a target that resolves outside it is refused with cli-path-outside-project (#75, #76, fixes #60).
  • A target path containing .. is refused when parsed (#75).
  • A target that is not a regular file, such as a FIFO, is refused instead of hanging list, check or resolve (#75).

Fewer silent surprises

  • list TARGET refuses a misspelled symbol, a missing file or an unknown namespace instead of printing "No links" and exiting 0 (#76).
  • A doc file whose name is not a valid source path is reported as a scan-invalid-source-path warning instead of being skipped silently (#71).
  • Naming a file under a symlinked directory warns with scan-explicit-path-symlinked instead of blaming a nonexistent ignore rule (#68).

Clearer errors

  • A failed link prints supdoc update PATH --yes with a path that runs from where you ran check, quoted (#74).
  • supdoc resolve FILE#SYMBOL says to write supdoc resolve FILE SYMBOL (#74).
  • resolve suggests only close symbol names, explains that line anchors are unsupported, and says to link the whole file when a file has no symbols (#72).
  • A broken supdoc.lock header says to write version = 1 or to recreate the lock, not to delete an entry (#69).
  • extends naming a directory, and include given a string, now say what to write instead (#73).
  • The unknown --format tip points at --output json and --json (#66).

Internal

  • CI token is read-only, actions are pinned to commit SHAs, and a cargo-deny job runs (#64).
  • Removed the unused Trace verbosity and the empty output::schema module. The cli-not-built error code is gone (#67).
  • Tests: dropped fixture-only goldens and added rename lock/config guards (#77); pinned the JSON fix object and the SUPDOC_YES / SUPDOC_DRY_RUN writes (#78).

New codes

  • scan-invalid-source-path (warning)
  • scan-explicit-path-symlinked (warning)
  • cli-resolve-fragment (error, exit 2)

supdoc v0.1.1

Choose a tag to compare

@aidenzepp aidenzepp released this 30 Oct 21:13
5d1260f

supdoc v0.1.1 is a fix release. Nothing in the lockfile format or the config schema changes, so v0.1.0 projects work unchanged.

Containment: what supdoc reads outside the project

The README now has a threat model: supdoc protects the contents of files outside the project root, not whether a path exists. These fixes make the code keep that promise.

  • extends is refused alike whether it leaves the root or goes through a symlink (#27).
  • Config discovery no longer reveals whether a symlink target exists (#23).
  • skill install refuses a project install through a symlink out of the root (#18).
  • resolve refuses a FILE outside the project root (#58).
  • Ignore files symlinked out of the root no longer decide what is scanned, and their rules are never quoted (#24).
  • A symlinked ignore file above the project root is not read (#56).

Ignore files work like git

  • Parent ignore files stop at the top of the git work tree (#48).
  • A nested repository or submodule starts a fresh ignore chain (#59).
  • A submodule's exclude file is read, global excludes are anchored at the work-tree top, and a .git counts only when git would use it (#49).
  • A symlinked .gitignore or .ignore inside the project is ignored, as git does (#42).
  • Sources under an unreadable directory are reported as unread (#17).
  • The README lists the remaining differences from git (#61).

Config and project discovery

  • One presence rule for supdoc.config.toml in discovery and the nested-project check (#37).
  • skill install finds the project root with config discovery (#39).
  • skill install --config refuses a path that is not an existing file (#57).

Messages and output

  • check and update print findings by file, then position (#22).
  • update closes on the plan and reports the line-endings change in JSONL (#15).
  • rename prints walk findings in text output (#47).
  • Files are named relative to the project in messages and runnable helps (#26).
  • A PATH that can't be looked up is reported as unreadable, not missing (#36).
  • extends errors say it must lead to a readable supdoc.config.toml (#38).
  • Help texts that misled are now runnable and effective (#19), and ignore-file wording no longer over-claims (#29).

Docs and packaging

  • README: threat model (#43, #61) and the schema_version compatibility policy (#14).
  • The packaged crate's tests compile and skip repository-only checks (#16).

Known issues

  • #60: supdoc list TARGET#symbol parses a file outside the root reached through an in-root symlink. No text or symbol names from that file are printed. Until this is fixed, the README's promise that supdoc lists no symbols from outside files does not hold for list.
  • #51: a file that an outer .gitignore ignores is still scanned. This is documented under "Differences from git".

Full changelog: v0.1.0...v0.1.1

supdoc v0.1.0

Choose a tag to compare

@aidenzepp aidenzepp released this 05 Nov 17:27

supdoc v0.1.0 is the first release. supdoc tracks links from documentation to code, such as [text](src/lib.rs#symbol), and reports when the code behind a link changes.

What it does

  • Link docs or code comments to code with ordinary Markdown links: [add](src/lib.rs#add) links one symbol, [lib](src/lib.rs) a whole file.
  • supdoc update --yes records a hash of every linked target in supdoc.lock. supdoc check compares the code with those hashes and fails when a linked target changed, so it works as a CI gate.
  • Links are read in Rust, TypeScript, JavaScript, Python, Go, Bash and Markdown files. Markdown headings are symbols too.

Commands

check, update, fix (repairs broken links whose fix is certain), list, resolve, init, config show, namespace list and namespace rename, schema, completions and skill install (supdoc's agent skill). Every command has --json output with a published JSON Schema.

Configuration

supdoc works without a config. supdoc init writes a supdoc.config.toml with every key commented out. Namespaces give a part of the project a short name, so auth:src/session.rs#login works from any file.

This GitHub release was added after the tag; the tag and the crate are unchanged.