LaTeX Scaffold
Convert an approved Markdown draft into a minimal, compilable LaTeX project. This is a deterministic format conversion — prose quality should already be addressed in the source draft.
When to Use
- Converting a literature review, survey, or report from Markdown to LaTeX for PDF output
- Turning meeting notes or drafts into a formatted document
- Bootstrapping a LaTeX project from an existing outline
- Any time you need md→tex without rewriting content
Inputs
- A Markdown file (
.md) — the draft to convert
- A
.bib file (optional) — if the draft contains citations
Outputs
- A
.tex file ready to compile with latex
- The fail-closed canonical
.latexmkrc if one does not already exist. Invoke the latex pre-flight to copy the canonical artifact; never synthesize selected directives.
Workflow
Step 1: Analyse the Draft
Read the Markdown file and inventory:
- Heading structure (determine
\section / \subsection depth)
- Citations (
[@Key] or [@Key1; @Key2] patterns)
- Tables (Markdown pipe tables)
- Math blocks (
$...$ inline, $$...$$ display)
- Figures (
)
- Code blocks (fenced with language)
- Whether an abstract section exists
Step 2: Create the LaTeX File
Apply these conversion rules:
| Markdown |
LaTeX |
# Title (first H1) |
\title{...} |
## Section |
\section{...} |
### Subsection |
\subsection{...} |
#### Subsubsection |
\subsubsection{...} |
## Abstract |
\begin{abstract}...\end{abstract} |
Headings starting with Appendix |
\appendix once, then \section{...} |
**bold** |
\textbf{...} |
*italic* |
\emph{...} |
`code` |
\texttt{...} |
[@Key] |
\citep{Key} |
[@Key1; @Key2] |
\citep{Key1,Key2} |
@Key (inline) |
\citet{Key} |
$...$ / $$...$$ |
Pass through unchanged |
- item |
\begin{itemize}\item ...\end{itemize} |
1. item |
\begin{enumerate}\item ...\end{enumerate} |
> quote |
\begin{quote}...\end{quote} |
 |
\begin{figure}[htbp]\includegraphics{path}\caption{caption}\end{figure} |
| Pipe tables |
\begin{table}[htbp]\begin{tabular}{...}...\end{tabular}\end{table} |
| Fenced code blocks |
\begin{verbatim}...\end{verbatim} |
--- (horizontal rule) |
\bigskip\hrule\bigskip or omit |
Preamble Template
\documentclass[a4paper,11pt]{article}
\usepackage[a4paper,margin=1in]{geometry}
\usepackage{hyperref}
\hypersetup{colorlinks=true,linkcolor=blue,citecolor=blue,urlcolor=blue}
\usepackage{booktabs}
\usepackage{tabularx}
\usepackage{graphicx}
\usepackage{amsmath,amssymb}
\usepackage{enumitem}
\usepackage[backend=biber,style=authoryear,natbib=true]{biblatex}
\addbibresource{references.bib}
\title{...}
\author{...}
\date{\today}
\begin{document}
\maketitle
% content here
\printbibliography
\end{document}
Adjust the preamble based on what the draft actually uses (e.g., skip graphicx if no figures). The natbib=true option provides \citet/\citep compatibility. If the project already uses natbib (e.g., with a journal .bst file), keep natbib — but for new scaffolds, biblatex is the default.
Step 3: Strip Markdown Residue
After conversion, scan the .tex file for any remaining Markdown syntax:
## heading markers** bold markers[@ citation markers- Pipe
| table syntax
![ image markers
These indicate incomplete conversion — fix them.
Step 4: Wire Bibliography
- If a
.bib file exists in the project, point \addbibresource{} to it
- If the project has a
references.bib, use that
- If no
.bib exists but citations are present, create placeholder comments: % TODO: create .bib with keys: Key1, Key2, ...
- Ensure
\printbibliography is at the end of the document (not \bibliography{})
Step 5: Compile and Verify
Run latex to compile. Verify:
Rules
- No content rewriting — this is format conversion only. Do not improve prose, fix grammar, or reorganise sections.
- Preserve all content — every paragraph, figure reference, and citation in the draft must appear in the
.tex output.
- Strip heading numbering — if the draft has numbered headings like
1.2 Methods, let LaTeX handle the numbering (just use \subsection{Methods}).
- Use
latex for compilation — never bare pdflatex or latexmk without out/ directory.
- Bold caption lines like
**Table 1. Description** immediately before a pipe table should become \caption{Description} inside a table float.
Cross-References
| Skill |
When to use alongside |
latex |
Compile the scaffolded .tex file |
latex |
For manual compilation config and .latexmkrc setup |
bib-validate |
After scaffolding to verify all citation keys resolve |
proofread |
After scaffolding for grammar and consistency check |
latex-template |
After scaffolding to verify preamble aligns with the working paper template |
Citation Contract
- Paperpile is the only source of truth for committed citation keys and BibTeX metadata.
- Before writing
\cite{key}, verify with paperpile get-item key and paperpile export-bib key.
- Resolve unknowns in order: DOI lookup → Paperpile substring search →
refpile semantic search → Paperpile verify.
- A DOI miss is not non-membership; continue with title/author search and refpile.
- If unresolved, write
\CiteTodo{slug}{title/author/year/DOI hint} — never a guessed key.
- Drafting sub-agents must not write/edit the active
.bib; only the orchestrator regenerates it from Paperpile exports.
- Stage genuine new refs under
.paperpile-import/ for manual Paperpile import; don't cite until Paperpile mints the key.
- Run
scripts/bib/citation_lint.py before commit; zero placeholders, zero non-Paperpile keys, zero hand-authored metadata.
See rules/paperpile-citations.md for the full workflow.
1---2name: latex-scaffold3description: "Convert an existing Markdown manuscript draft into a buildable LaTeX project with canonical structure and build configuration. Use when prose already exists but no LaTeX source tree does. Not for checking template drift in an existing project; use $latex-template."4argument-hint: "[path/to/draft.md]"5allowed-tools: Read, Write, Edit, Bash(latexmk*), Bash(mkdir*), Bash(ls*), Glob, Grep6skill-dependencies: [latex]7---89# LaTeX Scaffold1011Convert an approved Markdown draft into a minimal, compilable LaTeX project. This is a **deterministic format conversion** — prose quality should already be addressed in the source draft.1213## When to Use1415- Converting a literature review, survey, or report from Markdown to LaTeX for PDF output16- Turning meeting notes or drafts into a formatted document17- Bootstrapping a LaTeX project from an existing outline18- Any time you need md→tex without rewriting content1920## Inputs2122- A Markdown file (`.md`) — the draft to convert23- A `.bib` file (optional) — if the draft contains citations2425## Outputs2627- A `.tex` file ready to compile with `latex`28- The fail-closed canonical `.latexmkrc` if one does not already exist. Invoke the `latex` pre-flight to copy the canonical artifact; never synthesize selected directives.2930---3132## Workflow3334### Step 1: Analyse the Draft3536Read the Markdown file and inventory:37- Heading structure (determine `\section` / `\subsection` depth)38- Citations (`[@Key]` or `[@Key1; @Key2]` patterns)39- Tables (Markdown pipe tables)40- Math blocks (`$...$` inline, `$$...$$` display)41- Figures (``)42- Code blocks (fenced with language)43- Whether an abstract section exists4445### Step 2: Create the LaTeX File4647Apply these conversion rules:4849| Markdown | LaTeX |50|----------|-------|51| `# Title` (first H1) | `\title{...}` |52| `## Section` | `\section{...}` |53| `### Subsection` | `\subsection{...}` |54| `#### Subsubsection` | `\subsubsection{...}` |55| `## Abstract` | `\begin{abstract}...\end{abstract}` |56| Headings starting with `Appendix` | `\appendix` once, then `\section{...}` |57| `**bold**` | `\textbf{...}` |58| `*italic*` | `\emph{...}` |59| `` `code` `` | `\texttt{...}` |60| `[@Key]` | `\citep{Key}` |61| `[@Key1; @Key2]` | `\citep{Key1,Key2}` |62| `@Key` (inline) | `\citet{Key}` |63| `$...$` / `$$...$$` | Pass through unchanged |64| `- item` | `\begin{itemize}\item ...\end{itemize}` |65| `1. item` | `\begin{enumerate}\item ...\end{enumerate}` |66| `> quote` | `\begin{quote}...\end{quote}` |67| `` | `\begin{figure}[htbp]\includegraphics{path}\caption{caption}\end{figure}` |68| Pipe tables | `\begin{table}[htbp]\begin{tabular}{...}...\end{tabular}\end{table}` |69| Fenced code blocks | `\begin{verbatim}...\end{verbatim}` |70| `---` (horizontal rule) | `\bigskip\hrule\bigskip` or omit |7172### Preamble Template7374```latex75\documentclass[a4paper,11pt]{article}7677\usepackage[a4paper,margin=1in]{geometry}78\usepackage{hyperref}79\hypersetup{colorlinks=true,linkcolor=blue,citecolor=blue,urlcolor=blue}80\usepackage{booktabs}81\usepackage{tabularx}82\usepackage{graphicx}83\usepackage{amsmath,amssymb}84\usepackage{enumitem}85\usepackage[backend=biber,style=authoryear,natbib=true]{biblatex}86\addbibresource{references.bib}8788\title{...}89\author{...}90\date{\today}9192\begin{document}93\maketitle94% content here95\printbibliography96\end{document}97```9899Adjust the preamble based on what the draft actually uses (e.g., skip `graphicx` if no figures). The `natbib=true` option provides `\citet`/`\citep` compatibility. If the project already uses natbib (e.g., with a journal `.bst` file), keep natbib — but for new scaffolds, biblatex is the default.100101### Step 3: Strip Markdown Residue102103After conversion, scan the `.tex` file for any remaining Markdown syntax:104- `##` heading markers105- `**` bold markers106- `[@` citation markers107- Pipe `|` table syntax108- `![` image markers109110These indicate incomplete conversion — fix them.111112### Step 4: Wire Bibliography113114- If a `.bib` file exists in the project, point `\addbibresource{}` to it115- If the project has a `references.bib`, use that116- If no `.bib` exists but citations are present, create placeholder comments: `% TODO: create .bib with keys: Key1, Key2, ...`117- Ensure `\printbibliography` is at the end of the document (not `\bibliography{}`)118119### Step 5: Compile and Verify120121Run `latex` to compile. Verify:122- [ ] Document compiles without errors123- [ ] All citations resolve (or are marked as TODO)124- [ ] Tables render correctly125- [ ] Math renders correctly126- [ ] Page count is reasonable127128---129130## Rules131132- **No content rewriting** — this is format conversion only. Do not improve prose, fix grammar, or reorganise sections.133- **Preserve all content** — every paragraph, figure reference, and citation in the draft must appear in the `.tex` output.134- **Strip heading numbering** — if the draft has numbered headings like `1.2 Methods`, let LaTeX handle the numbering (just use `\subsection{Methods}`).135- **Use `latex`** for compilation — never bare `pdflatex` or `latexmk` without `out/` directory.136- **Bold caption lines** like `**Table 1. Description**` immediately before a pipe table should become `\caption{Description}` inside a `table` float.137138---139140## Cross-References141142| Skill | When to use alongside |143|-------|----------------------|144| `latex` | Compile the scaffolded `.tex` file |145| `latex` | For manual compilation config and `.latexmkrc` setup |146| `bib-validate` | After scaffolding to verify all citation keys resolve |147| `proofread` | After scaffolding for grammar and consistency check |148| `latex-template` | After scaffolding to verify preamble aligns with the working paper template |149150## Citation Contract151152<!-- paperpile-citation-contract -->1531. Paperpile is the only source of truth for committed citation keys and BibTeX metadata.1542. Before writing `\cite{key}`, verify with `paperpile get-item key` and `paperpile export-bib key`.1553. Resolve unknowns in order: DOI lookup → Paperpile substring search → `refpile` semantic search → Paperpile verify.1564. A DOI miss is **not** non-membership; continue with title/author search and refpile.1575. If unresolved, write `\CiteTodo{slug}{title/author/year/DOI hint}` — never a guessed key.1586. Drafting sub-agents must not write/edit the active `.bib`; only the orchestrator regenerates it from Paperpile exports.1597. Stage genuine new refs under `.paperpile-import/` for manual Paperpile import; don't cite until Paperpile mints the key.1608. Run `scripts/bib/citation_lint.py` before commit; zero placeholders, zero non-Paperpile keys, zero hand-authored metadata.161162See `rules/paperpile-citations.md` for the full workflow.
flonat