cargo-docs-md

Turn rustdoc JSON into markdown you can actually navigate.

Point it at your crate and get a directory of interlinked markdown files — click through modules, jump across crate boundaries, and go straight to source code. Your code and all your dependencies, documented and searchable in one place.

The generated_docs/ folder in this repo has 88 crates, 1,200+ markdown files, and 24,000+ searchable items generated from this tool's own dependency tree. Checkout the added docs and source code directly in repo to see how well it currently works (or not!).

Current Features

Clickable everything. Each file has breadcrumb navigation at the top. References to types, traits, and functions link to their definitions — even across crates. For example, regex_automata docs link directly to regex_syntax::hir::Hir.

*[cargo_docs_md](../index.md) / [generator](index.md) / [context](context/index.md)*

Source locations. Every item shows where it's defined. Click through to the exact file and line.

*Defined in `src/generator/context.rs:135-168`*

Search index. A search_index.json with every documented item — name, path, kind, and file location.

Installation

Requires Rust nightly (rustdoc JSON is unstable):

rustup toolchain install nightly
cargo install cargo-docs-md

Usage

cargo docs-md docs

That's it. Builds rustdoc JSON and generates markdown in one step.

cargo docs-md docs --primary-crate my_crate   # prioritize your crate for link resolution
cargo docs-md docs --exclude-private          # public items only
cargo docs-md docs --clean                    # full rebuild (cargo clean first)

Source file collection

To make source links work for dependencies, collect their source files first:

cargo docs-md collect-sources   # copies sources to .source_{timestamp}/
cargo docs-md docs              # auto-detects and links to them

This snapshots dependency sources at their exact versions, so links stay valid even after updates.

More options

For manual control, generate rustdoc JSON yourself:

RUSTDOCFLAGS='-Z unstable-options --output-format json' cargo +nightly doc
cargo docs-md --dir target/doc/ -o docs/

How it works

Reads rustdoc JSON and walks the module tree. For each module, collects all items, renders their docs, and resolves cross-reference links using rustdoc's link map.

Multi-crate workspaces get a unified link registry that tracks items across all crates. When the same name exists in multiple places, it resolves by checking: local crate first, then primary crate (if set), then any module match, then first available.

Known limitations

• No standard library links. References to Vec, String, Drop, etc. can't link to std docs since they're not in the generated output. They may incorrectly resolve to a same-named item in your dependencies.

• Nightly only. Rustdoc JSON is unstable and requires the nightly toolchain. The format can change between Rust versions.

• Ambiguous names. When multiple crates export the same name, the resolver picks one based on priority rules. This is usually correct, but occasionally produces unexpected links.

• Private item links. By default, private items are documented. If you later regenerate with --exclude-private, links pointing to those items will break.

Development

just help         # all commands
just test         # run tests
just lint         # clippy (pedantic + nursery)
just docs         # full rebuild

License

MIT