latex-scaffold

LaTeX Scaffold

Triggers & routing

• Trigger: latex scaffold, md→tex, LaTeX 项目骨架, 生成 main.tex.
• Use when: 需要 LaTeX/PDF 交付（例如 arxiv-survey-latex pipeline），且 draft 已生成/已进入写作阶段。

Convert the approved Markdown draft into a minimal, buildable LaTeX project.

This is a deterministic conversion step; prose quality should already be addressed in output/DRAFT.md.

Inputs

• output/DRAFT.md or output/TUTORIAL.md
• optional: citations/ref.bib

Outputs

• latex/main.tex (and any required LaTeX support files)

Layout policy

The machine-readable layout contract lives in assets/layout_profiles.json. The default profile uses a 1in A4 margin, includes a table of contents, and may split large tables. The bounded course_paper profile uses a documented 0.9in A4 margin, omits the table of contents, keeps a compact table whole when possible, and sets only the bibliography in \small. Body text remains 11pt. This profile is intended to respect an explicit page range, not to manufacture substantive completeness by shrinking the paper.

Workflow

1. Create latex/ directory if missing.
2. Create latex/main.tex with sections matching the outline.
3. Wire bibliography to citations/ref.bib when that file exists.

Quality checklist

• latex/main.tex exists.
• If citations/ref.bib exists, latex/main.tex references it.

Script

Quick Start

• uv run python .codex/skills/latex-scaffold/scripts/run.py --help
• uv run python .codex/skills/latex-scaffold/scripts/run.py --workspace <workspace>

All Options

• See --help (inputs/outputs are taken from the unit runner when used via pipeline)

Examples

• Build latex/main.tex from output/DRAFT.md or output/TUTORIAL.md:
  • uv run python .codex/skills/latex-scaffold/scripts/run.py --workspace <workspace>

Notes

• The generated latex/main.tex includes a table of contents (tocdepth=2) for readability.
• The course_paper profile omits that table of contents according to assets/layout_profiles.json; other profiles include it by default.
• Language default: the scaffold uses article (English-looking front matter). If the draft contains CJK characters, it switches to ctexart so the PDF renders correctly.
• Conversion rules (high level):
  • Headings ##/###/#### → \section/\subsection/\subsubsection (strips leading numeric prefixes like 1.2).
  • Headings starting with Appendix / 附录 trigger \appendix once, then render as appendix sections.
  • Bold caption lines like **Table 1. ...** / **Appendix Table A1. ...** immediately before a Markdown table become a LaTeX table float with \caption{...} and a stable \label{tab:...}.
  • ## Abstract → abstract environment.
  • [@Key] or [@Key1; @Key2] → \citep{Key} / \citep{Key1,Key2}.
  • Inline markdown **bold** / *italic* / `code` → \textbf{} / \emph{} / \texttt{}.

Troubleshooting

Issue: the generated latex/main.tex still contains Markdown markers

Fix:

• Re-run latex-scaffold and ensure the input output/DRAFT.md is clean (no ##, no **, no [@...] syntax that isn""t handled).

Issue: citations are missing in LaTeX

Fix:

• Ensure citations/ref.bib exists and the scaffold points bibliography to it; then compile with latex-compile-qa.