Doc2Quarto: Seamlessly Migrate from Docusaurus to Quarto

Introduction

Documentation is the backbone of any successful software project. As our needs evolve, so do our documentation tools. If you’ve been using Docusaurus and are considering a move to Quarto for its superior academic publishing capabilities, multi-format output, and Jupyter integration, you’re in the right place.

Doc2Quarto is a powerful command-line tool built in Rust that automates the tedious process of converting Docusaurus markdown files to Quarto format. It preserves your carefully crafted directory structure while transforming syntax elements to ensure a seamless migration.

Why Migrate to Quarto?

Before diving into the tool itself, let’s understand why you might want to make this transition:

Academic Publishing Excellence: Quarto provides native support for citations, cross-references, and LaTeX, making it ideal for technical documentation that requires scholarly rigor.
Multi-format Output: Generate PDF, HTML, DOCX, and more from the same source file. This flexibility is invaluable for teams that need to deliver documentation in multiple formats.
Jupyter Integration: Seamlessly embed executable code blocks and live visualizations, perfect for data science and computational documentation.
Enhanced Flexibility: Better suited for technical documentation, research outputs, and complex publishing workflows.

Key Features

Doc2Quarto handles the heavy lifting of migration with these powerful features:

Frontmatter Transformation

The tool intelligently converts Docusaurus-specific frontmatter fields to their Quarto equivalents:

Before (Docusaurus):

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

After (Quarto):

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

Admonition Conversion

One of the most significant syntax differences between the two platforms is how they handle callout boxes. Doc2Quarto automatically transforms these:

Before (Docusaurus):

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

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

After (Quarto):

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

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

The tool supports all standard admonition types:

Docusaurus	Quarto Callout
`note`	`note`
`tip`	`tip`
`info`	`note`
`caution`	`caution`
`warning`	`warning`
`danger`	`important`

Structure Preservation

Your carefully organized documentation structure remains intact. Doc2Quarto:

Maintains directory hierarchy
Copies image folders alongside converted files
Preserves relative paths and references
Changes file extensions from .md to .qmd

Progress Tracking

For large documentation projects, the tool provides visual feedback with:

Progress bars showing conversion status
Real-time file processing messages
Summary statistics upon completion

Installation

Doc2Quarto offers multiple installation methods to suit your workflow:

Option 1: Cargo (Rust Users)

If you have Rust installed:

cargo install doc2quarto

Option 2: Homebrew (macOS)

For macOS users with Homebrew:

brew install rvbug/tap/doc2quarto

Option 3: Debian Package (Linux)

Download and install the .deb package:

# 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

For the latest development version:

git clone https://github.com/rvbug/doc2quarto.git
cd doc2quarto
cargo install --path .

Verify Installation

After installation, verify it works:

doc2quarto --help

Usage

Using Doc2Quarto is straightforward. The basic command structure is:

doc2quarto --source ./docs --dest ./quarto-docs

Or using short flags:

doc2quarto -s ./docs -d ./quarto-docs

Command-Line Arguments

Flag	Short	Description	Required
`--source`	`-s`	Source directory containing Docusaurus markdown files	Yes
`--dest`	`-d`	Destination directory for Quarto files	Yes

Real-World Example

Let’s walk through a complete migration example:

Before Conversion

Your Docusaurus project structure:

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

Running the Conversion

doc2quarto --source ./docs --dest ./quarto-docs

Output:

Doc2Quarto - Docusaurus to Quarto Converter
=============================================
✓ Found 3 .md files in source directory

ℹ Found 3 markdown files
✓ Processed: intro.md
✓ Processed: quickstart.md
✓ Processed: reference.md
Conversion completed!

After Conversion

Your new Quarto structure:

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

Notice how the img folder is automatically copied alongside the converted files!

Technical Architecture

Doc2Quarto is built with modern Rust practices, leveraging these excellent libraries:

Clap: Ergonomic command-line argument parsing
Indicatif: Beautiful progress bars and spinners
Regex: Pattern matching for syntax transformation
WalkDir: Recursive directory traversal
Colored: Terminal output styling

The conversion pipeline follows a clean architecture:

Discovery: Recursively find all .md files
Processing: For each file:
- Read content
- Convert frontmatter
- Transform admonitions
- Preserve structure
Output: Write .qmd files with copied assets

Current Limitations

While Doc2Quarto handles the most common conversion scenarios, be aware of these limitations:

Known 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

Post-Migration Checklist

After running Doc2Quarto, follow these steps:

Review Generated Files: Spot-check a few .qmd files to ensure conversion quality
Test Rendering: Run quarto preview on your new documentation
Check References: Verify internal links and image references work correctly
Update Configuration: Create or update your _quarto.yml configuration file
Customize: Add Quarto-specific features like citations, cross-references, or executable code blocks

Future Roadmap

The project has exciting features planned:

Support for additional frontmatter fields
MDX component detection with migration warnings
Dry-run mode for preview before conversion
Configuration file support for custom transformations
Parallel processing for large documentation sets
Extended platform support (Windows, additional Linux distros)

Contributing

Doc2Quarto is open source and welcomes contributions! Whether you’re fixing bugs, adding features, or improving documentation, your help is appreciated.

Repository: github.com/rvbug/doc2quarto

Conclusion

Migrating documentation platforms doesn’t have to be painful. Doc2Quarto streamlines the transition from Docusaurus to Quarto, preserving your content structure while adapting syntax automatically.

With its robust feature set, multiple installation options, and active development, Doc2Quarto is the ideal tool for teams ready to unlock Quarto’s powerful publishing capabilities.

Ready to migrate? Install Doc2Quarto today and start enjoying the benefits of Quarto’s advanced documentation features!

--- title: "Doc2Quarto: Seamlessly Migrate from Docusaurus to Quarto" author: "Your Name" date: "2025-11-20" categories: [documentation, rust, quarto, docusaurus, migration] image: "./img/Doc2Quarto-cli.png" description: "A powerful CLI tool built in Rust to automate the conversion of Docusaurus markdown files to Quarto format" format: html: code-fold: false code-tools: true toc: true toc-depth: 3 --- ## Introduction Documentation is the backbone of any successful software project. As our needs evolve, so do our documentation tools. If you've been using Docusaurus and are considering a move to Quarto for its superior academic publishing capabilities, multi-format output, and Jupyter integration, you're in the right place. **Doc2Quarto** is a powerful command-line tool built in Rust that automates the tedious process of converting Docusaurus markdown files to Quarto format. It preserves your carefully crafted directory structure while transforming syntax elements to ensure a seamless migration. ## Why Migrate to Quarto? Before diving into the tool itself, let's understand why you might want to make this transition: **Academic Publishing Excellence** : Quarto provides native support for citations, cross-references, and LaTeX, making it ideal for technical documentation that requires scholarly rigor. **Multi-format Output** : Generate PDF, HTML, DOCX, and more from the same source file. This flexibility is invaluable for teams that need to deliver documentation in multiple formats. **Jupyter Integration** : Seamlessly embed executable code blocks and live visualizations, perfect for data science and computational documentation. **Enhanced Flexibility** : Better suited for technical documentation, research outputs, and complex publishing workflows. ## Key Features Doc2Quarto handles the heavy lifting of migration with these powerful features: ### Frontmatter Transformation The tool intelligently converts Docusaurus-specific frontmatter fields to their Quarto equivalents: **Before (Docusaurus):** ``` yaml --- title: "Getting Started" order: 1 --- ``` **After (Quarto):** ``` yaml --- title: "Getting Started" order: 1 --- ``` ### Admonition Conversion One of the most significant syntax differences between the two platforms is how they handle callout boxes. Doc2Quarto automatically transforms these: **Before (Docusaurus):** ``` markdown :::note Important Information This is a note with a custom title ::: :::warning Be careful with this operation ::: ``` **After (Quarto):** ``` markdown :::: {.callout-note} ## Important Information This is a note with a custom title :::: :::: {.callout-warning} Be careful with this operation :::: ``` The tool supports all standard admonition types: | Docusaurus | Quarto Callout | |------------|----------------| | `note` | `note` | | `tip` | `tip` | | `info` | `note` | | `caution` | `caution` | | `warning` | `warning` | | `danger` | `important` | ### Structure Preservation Your carefully organized documentation structure remains intact. Doc2Quarto: - Maintains directory hierarchy - Copies image folders alongside converted files - Preserves relative paths and references - Changes file extensions from `.md` to `.qmd` ### Progress Tracking For large documentation projects, the tool provides visual feedback with: - Progress bars showing conversion status - Real-time file processing messages - Summary statistics upon completion ## Installation Doc2Quarto offers multiple installation methods to suit your workflow: ### Option 1: Cargo (Rust Users) If you have Rust installed: ``` bash cargo install doc2quarto ``` ### Option 2: Homebrew (macOS) For macOS users with Homebrew: ``` bash brew install rvbug/tap/doc2quarto ``` ### Option 3: Debian Package (Linux) Download and install the `.deb` package: ``` bash # 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 For the latest development version: ``` bash git clone https://github.com/rvbug/doc2quarto.git cd doc2quarto cargo install --path . ``` ### Verify Installation After installation, verify it works: ``` bash doc2quarto --help ``` ## Usage Using Doc2Quarto is straightforward. The basic command structure is: ``` bash doc2quarto --source ./docs --dest ./quarto-docs ``` Or using short flags: ``` bash doc2quarto -s ./docs -d ./quarto-docs ``` ### Command-Line Arguments | Flag | Short | Description | Required | |----------------|----------------|-----------------------|------------------| | `--source` | `-s` | Source directory containing Docusaurus markdown files | Yes | | `--dest` | `-d` | Destination directory for Quarto files | Yes | ## Real-World Example Let's walk through a complete migration example: ### Before Conversion Your Docusaurus project structure: ``` docs/ ├── intro.md ├── guide/ │ ├── quickstart.md │ └── img/ │ └── diagram.png └── api/ └── reference.md ``` ### Running the Conversion ``` bash doc2quarto --source ./docs --dest ./quarto-docs ``` Output: ``` Doc2Quarto - Docusaurus to Quarto Converter ============================================= ✓ Found 3 .md files in source directory ℹ Found 3 markdown files ✓ Processed: intro.md ✓ Processed: quickstart.md ✓ Processed: reference.md Conversion completed! ``` ### After Conversion Your new Quarto structure: ``` quarto-docs/ ├── intro.qmd ├── guide/ │ ├── quickstart.qmd │ └── img/ │ └── diagram.png └── api/ └── reference.qmd ``` Notice how the `img` folder is automatically copied alongside the converted files! ## Technical Architecture Doc2Quarto is built with modern Rust practices, leveraging these excellent libraries: - **Clap**: Ergonomic command-line argument parsing - **Indicatif**: Beautiful progress bars and spinners - **Regex**: Pattern matching for syntax transformation - **WalkDir**: Recursive directory traversal - **Colored**: Terminal output styling The conversion pipeline follows a clean architecture: 1. **Discovery**: Recursively find all `.md` files 2. **Processing**: For each file: - Read content - Convert frontmatter - Transform admonitions - Preserve structure 3. **Output**: Write `.qmd` files with copied assets ## Current Limitations While Doc2Quarto handles the most common conversion scenarios, be aware of these limitations: ::: callout-warning ## Known 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 ::: ## Post-Migration Checklist After running Doc2Quarto, follow these steps: 1. **Review Generated Files**: Spot-check a few `.qmd` files to ensure conversion quality 2. **Test Rendering**: Run `quarto preview` on your new documentation 3. **Check References**: Verify internal links and image references work correctly 4. **Update Configuration**: Create or update your `_quarto.yml` configuration file 5. **Customize**: Add Quarto-specific features like citations, cross-references, or executable code blocks ## Future Roadmap The project has exciting features planned: - [ ] Support for additional frontmatter fields - [ ] MDX component detection with migration warnings - [ ] Dry-run mode for preview before conversion - [ ] Configuration file support for custom transformations - [ ] Parallel processing for large documentation sets - [ ] Extended platform support (Windows, additional Linux distros) ## Contributing Doc2Quarto is open source and welcomes contributions! Whether you're fixing bugs, adding features, or improving documentation, your help is appreciated. **Repository**: [github.com/rvbug/doc2quarto](https://github.com/rvbug/doc2quarto) ## Conclusion Migrating documentation platforms doesn't have to be painful. Doc2Quarto streamlines the transition from Docusaurus to Quarto, preserving your content structure while adapting syntax automatically. With its robust feature set, multiple installation options, and active development, Doc2Quarto is the ideal tool for teams ready to unlock Quarto's powerful publishing capabilities. Ready to migrate? Install Doc2Quarto today and start enjoying the benefits of Quarto's advanced documentation features!