brycewang-stanford/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 | | \begin{document}, \maketitle, \begin{abstract}, \appendix | 02-document-structure.md | | \textbf, \emph, \texttt, \footnote, \href | 03-text-formatting.md | | equation, align, gather, inline math delimiters | 04-math.md | | \cite, \citep, \citet, natbib/biblatex commands | 05-citations.md | | \label, \ref, \autoref, \eqref, prefix mapping | 06-cross-references.md | | \includegraphics, figure environment, subfigures | 07-figures.md | | tabular, table, booktabs, \multicolumn | 08-tables.md | | \section, \subsection, itemize, enumerate | 09-sections-lists.md | | Special characters, \newpage, verbatim, \input | 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 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.

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 — headings and lists
2. 05-citations.md — citations
3. 06-cross-references.md — labels and references
4. 07-figures.md — figures
5. 08-tables.md — tables
6. 04-math.md — math environments and delimiters
7. 03-text-formatting.md — inline formatting
8. 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)