cargo-docs-md

Turn rustdoc JSON into markdown you can actually navigate. Your code and all your dependencies, documented and searchable, navigable with reference links in one place.

The generated_docs/ folder in this repo has 90 crates, 1,286 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](index.md)*

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

For your own crate:

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

For dependencies (with collect-sources):

*Defined in [`compact_str-0.9.0/src/lib.rs:128`](../../.source_1765521767/compact_str-0.9.0/src/lib.rs#L128)*

Full method documentation. Methods include their complete documentation with examples:

- `fn push(&mut self, ch: char)`

  Appends the given char to the end of this CompactString.

  # Examples
  ...

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

# You need to run an extra command to collect your dependencies source code and 
# make a local copy directly into your project. It renames all Cargo.toml into Crate.toml 
# so that rust-analyzer ignores them by default.

cargo docs-md collect-sources
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.

Source collection options:

By default, the entire crate directory is copied to ensure all source files are available (including build.rs, modules outside src/, etc.).

Maximum detail output

For the most comprehensive documentation with all available information:

cargo docs-md collect-sources
cargo docs-md docs \
  --include-blanket-impls \
  --source-locations \
  --full-method-docs

This enables:

• Blanket impls — Shows From, Into, Any, Borrow, etc. implementations
• Source locations — Links to exact file and line for every item
• Full method docs — Complete method documentation with examples (not just summaries)

More options

Add more detail:

Reduce output:

Note: In multi-crate mode (docs subcommand or --dir), mdBook and search index are generated by default. Use --no-mdbook and --no-search-index to disable them.

Other 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