doc2quarto

A CLI tool to convert Docusaurus markdown files to Quarto format, preserving structure and transforming syntax for seamless migration.

Overview

doc2quarto automates the conversion of Docusaurus documentation to Quarto, handling:

• ✅ Frontmatter transformation (sidebar_position → order)
• ✅ Admonition conversion (:::note → Quarto callout blocks)
• ✅ Directory structure preservation
• ✅ Image folder copying
• ✅ Batch processing with progress tracking

Why Migrate to Quarto?

As documentation needs evolve, Quarto offers:

• Academic Publishing: Native support for citations, cross-references, and LaTeX
• Multi-format Output: Generate PDF, HTML, DOCX from the same source
• Jupyter Integration: Embed executable code and visualizations
• Flexibility: Better suited for technical documentation and research outputs

Read more about the migration rationale in this blog post.

Installation

Option 1: Install from crates.io (Rust Users)

# requires rust
$> cargo install doc2quarto

Option 2: Using homebrew on MacOS

$> brew install rvbug/tap/doc2quarto

Option 3: Debian (Linux)

Download the .deb package from releases:

# Download latest release 
$> wget https://github.com/rvbug/doc2quarto/releases/download/v0.1.1/doc2quarto_0.1.1-1_amd64.deb

# Install
$> sudo dpkg -i doc2quarto_0.1.1-1_amd64.deb

Option 4: Build from Source

Requires Rust to be installed.

$> git clone https://github.com/rvbug/doc2quarto.git

$> cd doc2quarto

$> cargo install --path .

Option 5: Install Locally

# Build and install to ~/.cargo/bin
cargo install --path .

# Now you can run 'doc2quarto' from anywhere
doc2quarto --help

Verify Installation

$> doc2quarto --help

Updating

Homebrew

$> brew upgrade doc2quarto

Cargo

$> cargo install doc2quarto

Uninstallation

Homebrew

$> cargo install doc2quarto

Cargo

$> cargo uninstall doc2quarto

Debian

$> sudo apt remove doc2quarto

Usage

# Basic usage
doc2quarto --source ./docs --dest ./quarto-docs

# Using short flags
doc2quarto -s ./docs -d ./quarto-docs

Arguments

Conversion Details

Frontmatter Transformation

Docusaurus:

---
title: "Getting Started"
sidebar_position: 1
---

Quarto:

---
title: "Getting Started"
order: 1
---

Admonition Conversion

Docusaurus:

:::note Important Information
This is a note with a custom title
:::

:::warning
Be careful with this operation
:::

Quarto:

:::: {.callout-note}
## Important Information
This is a note with a custom title
::::

:::: {.callout-warning}
Be careful with this operation
::::

Supported Admonition Types

Example

Before Conversion (Docusaurus)

docs/
├── intro.md
├── guide/
│   ├── quickstart.md
│   └── img/
│       └── diagram.png
└── api/
    └── reference.md

After Conversion (Quarto)

quarto-docs/
├── intro.qmd
├── guide/
│   ├── quickstart.qmd
│   └── img/
│       └── diagram.png
└── api/
    └── reference.qmd

Development

Prerequisites

• Rust 1.70 or higher
• Cargo

Running Tests

cargo test

Running with Development Build

cargo run -- --source ./test-docs --dest ./output

Project Structure

doc2quarto/
├── src/
│   └── main.rs          # Main conversion logic
├── tests/
│   ├── integration_test.rs
│   └── fixtures/        # Test markdown files
├── Cargo.toml
└── README.md

Limitations

• Content between admonitions and frontmatter is preserved as-is
• Custom Docusaurus components are not converted
• MDX features are not supported
• This is a one-time migration tool, not a continuous sync solution

Roadmap

• Support for more frontmatter fields

• MDX component detection and warnings

• Dry-run mode

• Configuration file support

• Parallel processing for large documentation sets

• Support for other OS

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built with Clap for CLI parsing
• Progress tracking via Indicatif
• Inspired by the need to bridge Docusaurus and Quarto ecosystems

Note: After migration, review the generated .qmd files and test rendering with Quarto before archiving your Docusaurus setup.