latex-to-quarto

LaTeX to Quarto Conversion

Convert a full LaTeX .tex article to a Quarto .qmd document that renders correctly

to HTML, PDF (Typst or LaTeX), and Word.

This skill handles the entire conversion pipeline: preamble extraction, document structure,

and all inline/block transformations.

This skill writes the output file (overwriting the input or writing to a second path).

Before writing, tell the user what file will be changed and remind them that git diff or

file history can recover the original.

---

Input Arguments

| Position | Required | Description |

|----------|----------|-------------|

| 1 | Yes | Path to the input .tex file (e.g., paper/paper.tex) |

| 2 | No | Output .qmd path. Defaults to same directory, .qmd extension. |

Example invocations:

/latex-to-quarto paper/paper.tex
/latex-to-quarto paper/paper.tex paper/paper.qmd

---

Quick Navigation: Use Which Reference

| Task | Reference File |

|------|----------------|

| \documentclass, \usepackage, \title, \author → YAML | [01-preamble-yaml.md](references/01-preamble-yaml.md) |

| \begin{document}, \maketitle, \begin{abstract}, \appendix | [02-document-structure.md](references/02-document-structure.md) |

| \textbf, \emph, \texttt, \footnote, \href | [03-text-formatting.md](references/03-text-formatting.md) |

| equation, align, gather, inline math delimiters | [04-math.md](references/04-math.md) |

| \cite, \citep, \citet, natbib/biblatex commands | [05-citations.md](references/05-citations.md) |

| \label, \ref, \autoref, \eqref, prefix mapping | [06-cross-references.md](references/06-cross-references.md) |

| \includegraphics, figure environment, subfigures | [07-figures.md](references/07-figures.md) |

| tabular, table, booktabs, \multicolumn | [08-tables.md](references/08-tables.md) |

| \section, \subsection, itemize, enumerate | [09-sections-lists.md](references/09-sections-lists.md) |

| Special characters, \newpage, verbatim, \input | [10-misc.md](references/10-misc.md) |

---

Step-by-Step Workflow

1. Parse Arguments

Identify the input .tex path (arg 1) and output path (arg 2).

If arg 2 is omitted, replace the .tex extension with .qmd in the same directory.

2. Read the File

Use the Read tool to load the full .tex file.

Hold the entire content in memory — you will produce one complete .qmd file at the end.

3. Extract and Convert the Preamble

Everything before \begin{document} is the preamble. Extract:

• \documentclass options → YAML format: settings
• \title{}, \author{}, \date{} → YAML title:, author:, date:
• \bibliography{file} / \addbibresource{file} → YAML bibliography:
• Package hints (geometry, setspace, natbib, biblatex) → YAML format options

See [01-preamble-yaml.md](references/01-preamble-yaml.md) for the full mapping table.

4. Strip Document Wrapper

Remove \begin{document} and \end{document}.

Remove \maketitle (title is rendered from YAML automatically).

Convert \begin{abstract}...\end{abstract} to YAML abstract:.

See [02-document-structure.md](references/02-document-structure.md).

5. Apply All Body Transformations

Work through the full document body and apply every applicable rule. Key principles:

• Preserve math regions: Never alter content inside $...$ or $$...$$ except to

move \label{} outside display math and convert delimiters (\(...\) → $...$).

• Handle nesting: \textbf{\emph{text}} → text. Process inner commands first.
• Be complete: Scan the entire file. Fix every instance of each pattern, not just the first.
• Apply all categories: Work through every reference file. A single paragraph may

require rules from multiple categories.

Apply reference files in this order (structural → inline):

1. [09-sections-lists.md](references/09-sections-lists.md) — headings and lists
2. [05-citations.md](references/05-citations.md) — citations
3. [06-cross-references.md](references/06-cross-references.md) — labels and references
4. [07-figures.md](references/07-figures.md) — figures
5. [08-tables.md](references/08-tables.md) — tables
6. [04-math.md](references/04-math.md) — math environments and delimiters
7. [03-text-formatting.md](references/03-text-formatting.md) — inline formatting
8. [10-misc.md](references/10-misc.md) — special characters and remaining patterns

6. Assemble the QMD File

Combine:

1. YAML front matter (between --- delimiters)
2. Converted document body (blank line after closing ---)

7. Write the Output File

Use the Write tool to write the complete .qmd file in one pass.

Do not use Edit for individual substitutions — a single full write ensures nothing is missed.

8. Report to the User

Tell the user:

• Output path written
• Summary of conversions by category (citation count, figure count, table count, etc.)
• Items requiring manual review with approximate line numbers
• Reminder to run quarto render to verify the output

---

Key Conceptual Differences: LaTeX vs. Quarto

Preamble → YAML Front Matter

LaTeX uses a \documentclass preamble; Quarto uses YAML front matter between ---.

% LaTeX preamble
\documentclass[12pt,a4paper]{article}
\usepackage[margin=1in]{geometry}
\title{My Paper}
\author{Jane Doe}
\date{\today}
\bibliography{refs}

# Quarto YAML front matter
---
title: "My Paper"
author: "Jane Doe"
date: today
bibliography: refs.bib
format:
  html: default
  pdf:
    documentclass: article
    papersize: a4
    fontsize: 12pt
    geometry: margin=1in
---

Math Content Is Preserved as LaTeX

Unlike conversion to Typst, Quarto uses LaTeX math directly.

Inline \(...\) → $...$; display \[...\] → $$...$$.

Math content (operators, symbols, matrices) stays unchanged.

Citations Use Pandoc Bracket Syntax

\citep{key} → [@key]; \citet{key} → @key.

The .bib file is referenced in YAML and left unchanged.

Cross-References Use @label Not \ref{}

\ref{fig:map} → @fig-map. Labels move from standalone \label{} commands

into element attribute blocks {#fig-map}.

---

Minimal Conversion Example

Input (paper.tex):

\documentclass[12pt]{article}
\usepackage{natbib}
\title{My Study}
\author{Jane Doe}
\date{2025}
\begin{document}
\maketitle
\begin{abstract}
We examine the effect of X on Y.
\end{abstract}
\section{Introduction}
Prior work \citep{smith2020} shows that $x > 0$.
See Figure~\ref{fig:map} for an overview.
\begin{figure}[h]
  \centering
  \includegraphics[width=0.8\textwidth]{figs/map.pdf}
  \caption{Study region.}
  \label{fig:map}
\end{figure}
\bibliography{refs}
\end{document}

Output (paper.qmd):

---
title: "My Study"
author: "Jane Doe"
date: 2025
bibliography: refs.bib
---

## Abstract

We examine the effect of X on Y.

# Introduction

Prior work [@smith2020] shows that $x > 0$.
See @fig-map for an overview.

![Study region.](figs/map.pdf){#fig-map width=80% fig-align="center"}

---

Patterns Requiring Manual Review

Flag these in your report with a suggested fix but no automatic conversion:

| Pattern | Suggested Quarto Equivalent |

|---------|------------------------------|

| \begin{theorem}, \begin{proof}, \begin{lemma} | ::: {.callout-note} div, or install a theorem extension |

| \newcommand{}{} / \renewcommand{}{} | Inline the macro expansion throughout; flag remaining uses |

| \input{file} / \include{file} | Inline contents or use {{< include file.qmd >}} shortcode |

| \vspace{} / \hspace{} | Remove or replace with CSS; no direct Quarto equivalent |

| \multicolumn{}{}{} in tables | Requires manual table restructuring |

| TikZ / PGF diagrams | Remove or replace with Mermaid/Observable JS |

| Beamer \begin{frame} | Switch to format: revealjs with ## slide headings |

| \bibliographystyle{} | Remove; use csl: in YAML if a specific citation style is needed |

| Multiple \label in one align block | Each labeled row may need its own equation block |

---

What to Preserve Unchanged

• LaTeX math content inside $...$ and $$...$$
• File paths in \includegraphics and \bibliography (adjust extension if needed)
• Existing @ref and [@citation] patterns already in correct Quarto form
• Content inside \begin{verbatim}...\end{verbatim} (convert to fenced block, keep content)