rustdoc-json-to-markdown 0.1.0

Convert rustdoc JSON output to clean, LLM-friendly markdown documentation
Documentation

rustdoc-json-to-markdown

🤖 AI-Generated Project: This tool was created entirely by Claude (Anthropic AI). See ATTRIBUTION.md for details.

Convert rustdoc's JSON output to markdown format for LLM consumption and convenient documentation viewing.

Motivation

Rustdoc generates excellent HTML documentation, but for LLM context or text-based viewing, markdown is more convenient. This tool converts rustdoc's JSON output (available via --output-format=json) into clean, structured markdown files.

Installation

From crates.io (recommended)

cargo install rustdoc-json-to-markdown

From source

git clone https://github.com/Crazytieguy/rustdoc-json-to-markdown
cd rustdoc-json-to-markdown
cargo install --path .

Usage

Quick Start

# 1. Generate rustdoc JSON (requires nightly Rust)
cargo +nightly rustdoc -- --output-format=json -Z unstable-options

# 2. Convert to markdown
rustdoc-json-to-markdown target/doc/your_crate.json -o docs/

# 3. View the generated markdown
cat docs/index.md

Detailed Usage

Step 1: Generate rustdoc JSON

# For a Cargo project (most common)
cargo +nightly rustdoc -- --output-format=json -Z unstable-options

# For a single file
rustdoc +nightly --output-format=json -Z unstable-options src/lib.rs

# For a specific dependency
cargo +nightly rustdoc -p dependency_name -- --output-format=json -Z unstable-options

This creates a JSON file at target/doc/<crate_name>.json

Step 2: Convert to Markdown

rustdoc-json-to-markdown target/doc/my_crate.json -o docs/

# With options
rustdoc-json-to-markdown target/doc/my_crate.json \
  --output docs/ \
  --include-private  # Include private items

Features

  • ✅ Converts all major rustdoc item types
    • Structs (with field tables and type information)
    • Enums (with variant tables showing kinds: Unit, Tuple, Struct)
    • Functions (with complete type signatures)
    • Traits (with method listings)
    • Type aliases and constants
    • Modules
  • ✅ Preserves documentation comments (already markdown)
  • ✅ Full type formatting for signatures and fields
  • ✅ Generates table of contents with links
  • ✅ Markdown tables for struct fields and enum variants
  • ✅ Generic parameter support
  • 🚧 Multi-file output (one file per module)
  • 🚧 Cross-reference links between items
  • 🚧 External crate links
  • 🚧 Trait implementation listings

Legend: ✅ Implemented | 🚧 Planned

Example Output

The tool generates clean, structured markdown with:

Table of Contents:

## Table of Contents

- [Point](#point)
- [Color](#color)
- [add](#add)

Struct with Field Table:

## Point

**Type:** Struct

Represents a 2D point in space.

**Fields:**

| Name | Type | Description |
|------|------|-------------|
| `x` | `i32` | The x coordinate |
| `y` | `i32` | The y coordinate |

Enum with Variant Table:

## Color

**Type:** Enum

**Variants:**

| Variant | Kind | Description |
|---------|------|-------------|
| `Red` | Unit | Red color |
| `Rgb` | Tuple(u8, u8, u8) | Custom RGB color |

Function with Type Signatures:

## add

**Type:** Function

Adds two numbers together.

\`\`\`rust
fn add(a: i32, b: i32) -> i32
\`\`\`

CLI Options

rustdoc-json-to-markdown <INPUT> [OPTIONS]

Arguments:
  <INPUT>  Path to rustdoc JSON file

Options:
  -o, --output <OUTPUT>              Output directory for markdown files [default: docs]
      --include-private              Include private items
  -h, --help                         Print help

Project Status

Phase 1 Complete (MVP) - The core functionality is implemented and tested with real-world crates:

  • Successfully tested with anyhow, serde_json, and custom crates
  • Generates well-formatted markdown with complete type information
  • Produces structured documentation suitable for LLM consumption and viewing

Note: The rustdoc JSON format itself is unstable and requires nightly Rust.

See PLAN.md for implementation details and Phase 2 roadmap.

Requirements

  • Rust nightly (to generate JSON output from rustdoc)
  • Cargo (to build this tool)

Dependencies

  • rustdoc-types v0.56 - Type definitions for rustdoc JSON (from crates.io)
  • serde_json - JSON parsing
  • anyhow - Error handling
  • clap - CLI interface with derive macros

Contributing

This is a personal project exploring rustdoc JSON output. Contributions welcome once the MVP is complete.

License

MIT or Apache-2.0 (same as Rust)

Related Projects