brycewang-stanford/quarto-clean

Quarto Clean

You clean a Quarto (.qmd) document by replacing LaTeX holdovers with correct Quarto/Pandoc syntax. Many authors migrate manuscripts from LaTeX or R Markdown and leave behind patterns (e.g., \citep{}, \ref{}, \textbf{}) that silently fail when rendering to Word or Typst PDF. This skill finds and fixes them all in a single pass.

This skill modifies the source file in place (or writes to a second path if supplied). 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 .qmd file to clean (e.g., paper/paper.qmd). Cleaned in place by default. | | 2 | No | Output path. If supplied, writes the cleaned file there instead of overwriting the input. |

Example invocations:

/quarto-clean paper/paper.qmd
/quarto-clean paper/paper.qmd drafts/paper-clean.qmd

---

Step-by-Step Workflow

1. Parse Arguments

Identify the input .qmd path (arg 1) and output path (arg 2, or same as arg 1 if omitted).

2. Read the File

Use the Read tool to load the entire file. Hold the full content in memory — you will rewrite it in one shot with the Write tool at the end.

3. Apply All Transformations

Work through the full content and apply every applicable transformation from the reference tables below. Key principles:

• Preserve protected regions: Never modify content inside fenced code blocks (``` or ~~~), inline code (` ), display math ($$...$$), inline math ($...$), or YAML front matter (--- to ---). Treat these regions as opaque.
• Handle nesting correctly: Because you understand the full document structure, handle nested commands naturally. \textbf{something \cite{key}} → **something [@key]**. \footnote{See \cite{key} for details} → ^[See [@key] for details].
• Apply all categories: Work through every category in the reference below. A single command (\textbf{\emph{text}}) may require multiple rules (***text***).
• Be complete: Scan the entire file. Do not stop after the first occurrence of a pattern — fix every instance.

4. Write the Cleaned File

Use the Write tool to overwrite the output path with the fully cleaned content. Do not use Edit for individual substitutions — rewrite the whole file so nothing is missed.

5. Report to the User

Tell the user:

• Output path written
• Summary of fixes by category (how many of each type were converted)
• Items requiring manual review — any patterns you could not safely convert automatically (list with approximate line numbers so the user can find them)
• Reminder to run quarto render to verify

---

Transformation Reference

Apply every applicable rule. Rules are ordered so that inner/simpler commands are converted before outer/wrapper commands, which handles nesting correctly.

Citations

Convert all natbib/biblatex citation commands to Pandoc bracket syntax. These must work in all output formats (HTML, Word, Typst PDF).

| LaTeX | Quarto | Notes | |-------|--------|-------| | \cite{key} | [@key] | | | \citep{key} | [@key] | | | \citep{a,b} | [@a; @b] | Split comma-separated keys | | \citep[p.~5]{key} | [@key, p. 5] | Locator (suffix only) | | \citep[see][p.~5]{key} | [see @key, p. 5] | Prefix + locator | | \citet{key} | @key | Narrative / in-text citation | | \citet{a,b} | @a and @b | Multiple narrative keys | | \citealt{key} | @key | No parentheses | | \citeauthor{key} | @key | Loses "author-only" semantics; flag in report | | \citeyear{key} | [-@key] | Year only; suppresses author | | \nocite{key} | Move to YAML nocite: '@key' | Remove from body; add to front matter | | \nocite{*} | Move to YAML nocite: '@*' | |

Cross-References

Convert \label and \ref commands. The label prefix maps directly:

| LaTeX prefix | Quarto prefix | Example LaTeX | Example Quarto | |--------------|--------------|---------------|----------------| | fig: | fig- | \label{fig:map} → {#fig-map} | \ref{fig:map} → @fig-map | | tab: or table: | tbl- | \label{tab:results} | @tbl-results | | sec: or section: | sec- | \label{sec:intro} | @sec-intro | | eq: or eqn: | eq- | \label{eq:ols} | @eq-ols | | lst: | lst- | | | | thm:, lem:, prop:, etc. | same with - | | |

Rules:

• \ref{type:name} → @type-name (replace : with -, map prefix per table)
• \autoref{type:name} → @type-name
• \eqref{eq:name} → @eq-name
• Drop redundant type words: Figure \ref{fig:x} → @fig-x (Quarto auto-generates "Figure N"). Same for "Table", "Section", "Equation", "Appendix".
• \label{type:name} must be moved to the appropriate Quarto element as {#type-name}:
  • On a figure: ![Caption](file){#fig-name}
  • On a table caption: : Caption {#tbl-name}
  • On a heading: ## Title {#sec-name}
  • On display math: $$...$$ {#eq-name} (on the line after $$)
• Replace underscores with hyphens in the name part: fig:my_fig → {#fig-my-fig}

R Markdown Chunk Options

Convert old-style inline chunk options to #| YAML comments. The fence header becomes bare (language only), and each option becomes a #| line inside the chunk.

Before:

```{r my-label, echo=FALSE, fig.cap="My figure", fig.width=6, out.width="80%"}

After:

```{r}
#| label: my-label
#| echo: false
#| fig-cap: "My figure"
#| fig-width: 6
#| out-width: "80%"

Option name mapping (dots → dashes, booleans → lowercase):

| Old | New | |-----|-----| | fig.cap | fig-cap | | fig.width | fig-width | | fig.height | fig-height | | fig.align | fig-align | | fig.alt | fig-alt | | fig.subcap | fig-subcap | | fig.pos | fig-pos | | fig.env | fig-env | | out.width | out-width | | out.height | out-height | | echo=FALSE | echo: false | | eval=FALSE | eval: false | | warning=FALSE | warning: false | | message=FALSE | message: false | | include=FALSE | include: false | | cache=TRUE | cache: true | | results='hide' | output: false | | results='asis' | output: asis | | tidy=TRUE | (remove — deprecated) |

The first unnamed token in the old header is the label: {r my-label, echo=FALSE} → #| label: my-label.

Figures

| LaTeX | Quarto | |-------|--------| | \includegraphics{file} | ![](file) | | \includegraphics[width=0.8\textwidth]{file} | ![](file){width=80%} | | \includegraphics[width=5cm]{file} | ![](file){width=5cm} | | \centering inside figure env | fig-align="center" attribute on the figure |

Full figure environment:

\begin{figure}[h]
  \centering
  \includegraphics[width=0.8\textwidth]{figs/map.pdf}
  \caption{A map of the study region.}
  \label{fig:map}
\end{figure}

Becomes:

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

• \begin{figure*} → add fig-env="figure*" to the attribute block
• For computational figures in code chunks, use #| fig-cap: and #| label: fig-...

Tables

Markdown / pipe tables:

| Col A | Col B |
|:------|------:|
| val   | 1.23  |

: My table caption. {#tbl-results}

• Column alignment from tabular spec: l → :---, r → ---:, c → :---:
• Caption goes below the table, after : , with {#tbl-label} at the end
• For computational tables (knitr/kable output), add chunk options instead:

  #| label: tbl-results
  #| tbl-cap: "My table caption."
  

LaTeX table environment → Quarto pipe table:

\begin{table}
  \caption{My table caption.}
  \label{tab:results}
  \begin{tabular}{lrr}
    \hline
    Method & Estimate & SE \\
    \hline
    OLS & 1.23 & 0.45 \\
    IV  & 1.89 & 0.67 \\
    \hline
  \end{tabular}
\end{table}

Becomes:

| Method | Estimate |   SE |
|:-------|--------:|-----:|
| OLS    |    1.23 | 0.45 |
| IV     |    1.89 | 0.67 |

: My table caption. {#tbl-results}

Text Formatting

Handle nesting: \textbf{\emph{text}} → ***text***.

| LaTeX | Quarto | |-------|--------| | \textbf{text} | **text** | | \textit{text} | *text* | | \emph{text} | *text* | | \texttt{text} | `text` | | \underline{text} | [text]{.underline} | | \textsc{text} | [text]{.smallcaps} | | \textsuperscript{x} | ^x^ | | \textsubscript{x} | ~x~ | | \sout{text} | ~~text~~ | | \footnote{text} | ^[text] |

Math

| LaTeX | Quarto | |-------|--------| | \(x + y\) | $x + y$ | | \[x + y\] | $$x + y$$ | | \begin{equation} / \end{equation} | $$ / $$ with {#eq-name} after closing $$ | | \begin{align} / \end{align} | $$\begin{aligned} / \end{aligned}$$ | | \label{eq:name} inside math | Remove from math body; add {#eq-name} after closing $$ |

Hyperlinks

| LaTeX | Quarto | |-------|--------| | \url{https://...} | <https://...> | | \href{url}{text} | [text](url) |

Special Characters and Spacing

| LaTeX | Quarto | Notes | |-------|--------|-------| | \& | & | Outside math | | \% | % | Outside math | | \ldots or \dots | ... | | | \footnote{text} | ^[text] | (also in Text Formatting above) | | \noindent | (remove) | | | \par | blank line | | | \newline or \\ | blank line or two trailing spaces | Paragraph break in prose | | \newpage or \clearpage | {{< pagebreak >}} | | | ~ (tie space) | or   | Context-dependent |

Section Headings

| LaTeX | Quarto | |-------|--------| | \section{Title} | # Title | | \subsection{Title} | ## Title | | \subsubsection{Title} | ### Title | | \paragraph{Title} | #### Title | | \section*{Title} | # Title {.unnumbered} | | \section{Title}\label{sec:x} | # Title {#sec-x} |

If a \label{sec:x} appears on the line following a heading, merge it into the heading's attribute block: ## Methods {#sec-methods}.

List Environments

| LaTeX | Quarto | |-------|--------| | \begin{itemize} / \item | Unordered list with - | | \begin{enumerate} / \item | Ordered list with 1. | | \begin{description} / \item[Term] | : Term\n: definition |

Nested lists: indent continuation lines by two spaces per level.

Abstract and Front Matter

Move these from the document body to YAML:

\begin{abstract}
  We study the effect of X on Y...
\end{abstract}

→ YAML field:

abstract: |
  We study the effect of X on Y...

Similarly for \title{}, \author{}, \date{} appearing in the body — move to YAML title:, author:, date: fields.

---

Patterns That Need Judgment

Flag these in your report if you encounter them, with a suggested fix but no automatic conversion (the content depends too much on context):

• Custom LaTeX environments (\begin{theorem}, \begin{proof}, \begin{lemma}, \begin{frame}, etc.) → suggest converting to ::: {.callout-note} or a theorem div
• \vspace{} / \hspace{} → no direct Quarto equivalent; suggest removing or using CSS
• \multicolumn{}{}{} in tables → requires restructuring the table manually
• \citeauthor{key} → converted to @key but the "author only" rendering is lost; suggest rephrasing (e.g., "Smith [-@smith2020]")
• cite-method: natbib or cite-method: biblatex in YAML → should likely be removed for non-LaTeX output formats; flag for user decision
• \\[6pt] or \\[1em] (spacing in math display) → the spacing argument is not valid in Quarto; convert to \\ and note the spacing is lost

---

What to Preserve Unchanged

• All content inside ```...``` fenced code blocks (including chunk body code)
• All content inside `...` inline code
• All content inside $...$ inline math and $$...$$ display math (except \label{} which must be moved outside, and \( \) / \[ \] delimiters which must be converted)
• YAML front matter between --- delimiters
• Quarto shortcodes {{< ... >}}
• Existing @ref cross-references and [@citation] citations that are already correct
• Pandoc div/span syntax ::: and []{} that is already valid Quarto