Quarto Clean

You clean a Quarto (

.qmd

\citep{}

\ref{}

\textbf{}

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

Input Arguments

.qmd

paper/paper.qmd

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

2. Read the File

Use the

Read

Write

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

Edit

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).

\cite{key}

[@key]

\citep{key}

[@key]

\citep{a,b}

[@a; @b]

\citep[p.~5]{key}

[@key, p. 5]

\citep[see][p.~5]{key}

[see @key, p. 5]

\citet{key}

@key

\citet{a,b}

@a and @b

\citealt{key}

@key

\citeauthor{key}

@key

\citeyear{key}

[-@key]

\nocite{key}

nocite: '@key'

\nocite{*}

nocite: '@*'

Cross-References

Convert

\label

\ref

fig:

fig-

\label{fig:map}

{#fig-map}

\ref{fig:map}

@fig-map

tab:

table:

tbl-

\label{tab:results}

@tbl-results

sec:

section:

sec-

\label{sec:intro}

@sec-intro

eq:

eqn:

eq-

\label{eq:ols}

@eq-ols

lst:

lst-

thm:

lem:

prop:

-

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

#|

#|

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):

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

The first unnamed token in the old header is the label:

{r my-label, echo=FALSE}

#| label: my-label

Figures

\includegraphics{file}

![](file)

\includegraphics[width=0.8\textwidth]{file}

![](file){width=80%}

\includegraphics[width=5cm]{file}

![](file){width=5cm}

\centering

fig-align="center"

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***

\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

\(x + y\)

$x + y$

\[x + y\]

$$x + y$$

\begin{equation}

\end{equation}

$$

$$

{#eq-name}

$$

\begin{align}

\end{align}

$$\begin{aligned}

\end{aligned}$$

\label{eq:name}

{#eq-name}

$$

Hyperlinks

\url{https://...}

<https://...>

\href{url}{text}

[text](url)

Special Characters and Spacing

\&

&

\%

%

\ldots

\dots

...

\footnote{text}

^[text]

\noindent

\par

\newline

\\

\newpage

\clearpage

{{< pagebreak >}}

~

 

Section Headings

\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}

## Methods {#sec-methods}

List Environments

\begin{itemize}

\item

-

\begin{enumerate}

\item

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{}

title:

author:

date:

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