/quarto-clean

name: quarto-clean
description: 'Cleans a Quarto (.qmd) file by replacing LaTeX holdovers with proper Quarto/Pandoc syntax so the document renders correctly to HTML, PDF (Typst/LaTeX), and Word. Fixes citations (\citep → [@key]), cross-references (\ref → @label), figures (\includegraphics → markdown), tables, text formatting (\textbf → **bold**), inline math (\( \) → $ $), hyperlinks (\href → [text](url)), footnotes (\footnote → ^[]), list environments, section headings, and R Markdown chunk options (dot-style → #| YAML). Use when asked to clean, fix, modernize, or port a Quarto or R Markdown document; when LaTeX commands appear in a .qmd file; when a document fails to render to Word or Typst; or when citations/cross-references do not appear in non-LaTeX output.'
metadata:
  author: Christopher T. Kenny
  version: 1.1

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: `{#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 na