A CLI tool to convert Docusaurus markdown files to Quarto format, preserving structure and transforming syntax for seamless migration.
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
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.
# requires rust
$> cargo install doc2quarto$> brew install rvbug/tap/doc2quartoDownload 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
Requires Rust to be installed.
$> git clone https://github.com/rvbug/doc2quarto.git
$> cd doc2quarto
$> cargo install --path .# Build and install to ~/.cargo/bin
cargo install --path .
# Now you can run 'doc2quarto' from anywhere
doc2quarto --help$> doc2quarto --help$> brew upgrade doc2quarto$> cargo install doc2quarto$> cargo install doc2quarto$> cargo uninstall doc2quarto$> sudo apt remove doc2quarto# Basic usage
doc2quarto --source ./docs --dest ./quarto-docs
# Using short flags
doc2quarto -s ./docs -d ./quarto-docs| Flag | Short | Description | Required |
|---|---|---|---|
--source |
-s |
Source directory containing Docusaurus markdown files | Yes |
--dest |
-d |
Destination directory for Quarto files | Yes |
Docusaurus:
---
title: "Getting Started"
sidebar_position: 1
---Quarto:
---
title: "Getting Started"
order: 1
---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
::::| Docusaurus | Quarto |
|---|---|
note |
note |
tip |
tip |
info |
note |
caution |
caution |
warning |
warning |
danger |
important |
docs/
├── intro.md
├── guide/
│ ├── quickstart.md
│ └── img/
│ └── diagram.png
└── api/
└── reference.md
quarto-docs/
├── intro.qmd
├── guide/
│ ├── quickstart.qmd
│ └── img/
│ └── diagram.png
└── api/
└── reference.qmd
- Rust 1.70 or higher
- Cargo
cargo testcargo run -- --source ./test-docs --dest ./outputdoc2quarto/
├── src/
│ └── main.rs # Main conversion logic
├── tests/
│ ├── integration_test.rs
│ └── fixtures/ # Test markdown files
├── Cargo.toml
└── README.md
- 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
- 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
This project is licensed under the MIT License - see the LICENSE file for details.
- 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.