# rd2qmd
A fast Rd-to-Quarto Markdown converter written in Rust, with intelligent link resolution.
## Features
- **Blazing fast**: Converts 228 ggplot2 docs in ~0.13s with parallel processing
- **Smart link resolution**: Automatically resolves `\link{}` references to correct output files
- **External package links**: Resolves cross-package links using pkgdown URL conventions (e.g., `\link[dplyr]{mutate}` → `https://dplyr.tidyverse.org/reference/mutate.html`)
- **Topic index generation**: Outputs JSON index with topic metadata (name, title, aliases, lifecycle) for building reference sites
- **Quarto-ready**: Generates `.qmd` files with `{r}` executable code blocks and YAML frontmatter
- **Flexible Arguments format**: Supports Quarto native List-Tables (default), Pandoc Grid Tables, GFM Pipe Tables, and Markdown loose lists for the Arguments section (`--arguments-format list-table|grid-table|pipe-table|list`)
- **pkgdown-compatible metadata**: Adds `pagetitle` in pkgdown style (`"
— "`) for SEO
- **No R required**: Pure Rust binary with no runtime R dependency
## Installation
### Cargo
```sh
cargo install --locked rd2qmd
```
### GitHub Releases
Pre-built binaries for Linux, macOS, and Windows are available on the [Releases](https://github.com/eitsupi/rd2qmd/releases) page. You can also use the installer scripts:
macOS / Linux:
```sh
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/eitsupi/rd2qmd/releases/latest/download/rd2qmd-installer.sh | sh
```
Windows (PowerShell):
```powershell
powershell -ExecutionPolicy Bypass -c "irm https://github.com/eitsupi/rd2qmd/releases/latest/download/rd2qmd-installer.ps1 | iex"
```
## Usage
rd2qmd provides four subcommands:
- `convert` — convert Rd files to Quarto Markdown, R Markdown, or standard Markdown
- `parse` — parse Rd files to AST JSON (see [AST JSON I/O](#ast-json-io))
- `index` — generate a JSON topic index (see [Topic index generation](#topic-index-generation))
- `init` — create a starter `_rd2qmd.toml` configuration file
`-v, --verbose` and `-q, --quiet` are global flags available on every subcommand.
### Basic usage
```bash
# Convert a single file (outputs to same directory)
rd2qmd convert file.Rd
# Convert to a specific output file
rd2qmd convert file.Rd -o output.qmd
# Convert to standard Markdown instead of Quarto
rd2qmd convert file.Rd -f md
```
### Directory conversion
When converting a directory, rd2qmd builds an alias index for internal link resolution:
```bash
# Convert all .Rd files in a directory
rd2qmd convert man/ -o docs/
# Process subdirectories recursively
rd2qmd convert man/ -o docs/ -r
# Use parallel processing with 4 jobs
rd2qmd convert man/ -o docs/ -j4
```
### Options
| Option | Description |
|--------|-------------|
| `-o, --output ` | Output file or directory |
| `-f, --format ` | Output format: `qmd` (default), `md`, or `rmd` |
| `-j, --jobs ` | Number of parallel jobs (defaults to CPU count) |
| `-r, --recursive` | Process directories recursively |
| `--no-frontmatter` | Disable YAML frontmatter; use this for a visible body `# Title` in Markdown consumers that do not render YAML titles |
| `--no-pagetitle` | Skip pkgdown-style `pagetitle` metadata (`" — "`) |
| `--quarto-code-blocks ` | Use `{r}` code blocks (auto-set based on format) |
| `--describe-format ` | Description list format: `pandoc-definition-list` (default; unsupported by q2), `quarto-definition-list` (Quarto 1.11.7+ / q2), `list`, or `headings` (CommonMark/GFM) |
| `--arguments-format ` | Arguments format: `list-table` (default), `grid-table`, `pipe-table`, or `list` |
| `--input-format ` | Input format: `rd` (default) or `ast` (see [AST JSON I/O](#ast-json-io)) |
| `-v, --verbose` | Verbose output |
| `-q, --quiet` | Only show errors |
### Link resolution options
Rd help topic links come in two classes, and each class has its own
resolution chain. Every step is a URL template; `{package}`, `{topic}`, and
`{file}` placeholders are filled per link:
- **Qualified links** (`\link[pkg]{topic}`) name their target package:
1. `package_urls` map — per-package URL templates, from the config file
and/or automatic external link resolution (see below)
2. `--external-link-url` template
3. plain inline code (link target dropped)
- **Unqualified links** (`\link{topic}`) don't name a package:
1. the package's own alias index (directory mode), rendered with the
`internal_link_url` template (default: `{file}.