latex-to-quarto

name	latex-to-quarto
description	Converts LaTeX article-class .tex documents to Quarto .qmd format for multi-format publishing (HTML, PDF, Word). Use when asked to convert, port, migrate, or translate a .tex LaTeX file to Quarto; when porting an academic paper or manuscript from LaTeX to Quarto; when a .tex document needs to render to HTML, Word, or Typst PDF. Covers preamble → YAML front matter, section headings, text formatting, math, citations (natbib/biblatex), cross-references, figures, tables, lists, footnotes, hyperlinks, and special characters.
metadata	{"author":"Christopher T. Kenny","version":1}

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)