mystquarto
Bidirectional MyST ↔ Quarto converter. Transforms directives, roles, config files, and frontmatter between the two academic writing formats.
The problem
MyST Markdown
Jupyter Book ecosystem. Sphinx directives and roles. Great for executable notebooks.
```{code-cell} python
:tags: [hide-input]
df.plot()
```
As shown in {numref}`fig-results`,
the effect is {cite}`smith2024`.Quarto
Pandoc-based publishing. Callouts and cross-references. Better PDF and web output.
```{python}
#| code-fold: true
df.plot()
```
As shown in @fig-results,
the effect is [@smith2024].Both are excellent for academic writing, but their syntax is incompatible. No converter existed — until now.
Usage
Convert a MyST project to Quarto
myst2quarto docs/ -o docs-quarto/Convert a Quarto project to MyST
quarto2myst docs/ -o docs-myst/Run without installing
uvx myst2quarto docs/Unified CLI
mystquarto to-quarto docs/ --dry-run
mystquarto to-myst docs/ --in-placeWhat it converts
Block directives
```{code-cell} python ```{python} :tags: [hide-input] #| code-fold: true ```{figure} path {#fig-id} ```{note} ::: {.callout-note} ```{math} :label: $$ ... $$ {#eq-id} ::::{tab-set} ::: {.panel-tabset} Inline roles
{eval}`expr` `{python} expr` {cite}`key` [@key] {cite:t}`key` @key {numref}`fig-id` @fig-id {eq}`label` @eq-label {doc}`path` [path](path.qmd) Config and frontmatter
myst.yml _quarto.yml project.toc book.chapters project.exports format: pdf/docx kernelspec: python3 jupyter: python3 Plus 13 more block directive types, file extension renaming (.md ↔ .qmd), asset copying, and more. All conversions are bidirectional.
How it works
Line scanner
Regex-based scanner processes files line by line, detecting backtick and colon fences with a directive stack for proper nesting
Transform rules
Each directive and inline role has a paired forward and reverse transform function — 13 block types, 9 inline roles
Lightweight
Only click + pyyaml as dependencies. No markdown-it-py, myst-parser, or docutils — keeps install fast and simple
Get started
Install
pip install mystquartoConvert
# MyST → Quarto
myst2quarto docs/ -o docs-quarto/
# Quarto → MyST
quarto2myst docs/ -o docs-myst/Build
cd docs-quarto/ && quarto renderYour MyST project now builds with Quarto