zhangys11/agent-skills

Markdown to LaTeX Converter (md2tex)

Convert academic Markdown manuscripts to LaTeX .tex files suitable for journal submission. Handles the full conversion pipeline: headers, bold/italic, pipe tables, images, display/inline math, bullet lists, Unicode special characters, and citation formatting.

Quick Start

# Simple: convert a single .md to article-class .tex
python3 scripts/md2tex.py paper.md -o output/

# Choose document class preset
python3 scripts/md2tex.py paper.md -o output/ --class ieeetran
python3 scripts/md2tex.py paper.md -o output/ --class revtex

# Multi-file: main manuscript + appendix as supplemental
python3 scripts/md2tex.py main.md --appendix appendix.md -o output/ --class revtex

# Custom preamble overrides (add packages, commands, etc.)
python3 scripts/md2tex.py paper.md --preamble my_preamble.tex -o output/

# Compile PDFs after generation
python3 scripts/md2tex.py paper.md -o output/ --compile

Paths above are relative to this skill's base directory.

What It Does

The script reads Markdown and produces LaTeX by applying these conversions:

Markdown	LaTeX
## Section	\section{Section}
### Subsection	\subsection{Subsection}
#### Subsubsection	\subsubsection{Subsubsection}
**bold**	\textbf{bold}
*italic*	\textit{italic} (math-aware: skips $...$)
$$...$$	$$...$$ (pass-through)
$...$	$...$ (pass-through)
| ... | pipe tables	\begin{tabular}...\end{tabular}
	\begin{figure}\includegraphics...\caption...\end{figure}
![[path|alt]] (Obsidian)	Same as above
- bullet	\begin{itemize}\item...\end{itemize}
α, β, ∞, →, × etc.	$\alpha$, $\beta$, $\infty$, $\to$, $\times$
--- (em-dash)	--- (preserved)

Additional Processing

• Image captions: Looks ahead for **Fig. N | ...** or **Fig. N.** lines after images to build proper \caption{...}.
• Table captions: Looks for **Table N | ...** or **TABLE N** blocks preceding pipe tables.
• Unicode math: Maps α β γ ε λ μ π ρ σ ω Γ Λ Σ Ω ∞ → ← × ± ≤ ≥ ≈ ≠ ¬ to LaTeX equivalents.
• Accented chars: Maps é è ê ñ ö ü â î ô to LaTeX escapes.
• Smart quotes: "" '' to `` ''.
• Polish ł: Białynicki → Bia{\l}ynicki for correct rendering.
• Blank line cleanup: Collapses 4+ blank lines to 2.
• Blockquote removal: Optionally strips > ... lines.

Document Class Presets

Preset	Document Class	Use Case
article (default)	\documentclass[12pt]{article}	General papers, arXiv
revtex	\documentclass[aps,pra,preprint]{revtex4-2}	Physical Review journals
ieeetran	\documentclass[journal,onecolumn,12pt]{IEEEtran}	IEEE transactions

Each preset includes appropriate packages (graphicx, amsmath, amssymb, hyperref, booktabs, array).

Custom Preamble

Create a .tex file containing your full preamble (packages, commands, etc.) and pass it with --preamble. The default for each preset is overridden.

Example my_preamble.tex:

\documentclass[aps,pra,reprint]{revtex4-2}
\usepackage{graphicx}
\usepackage{amsmath,amssymb}
\usepackage{hyperref}
\usepackage{booktabs}
\usepackage{xcolor}
\newcommand{\pbox}[2]{\parbox{#1}{\vspace{4pt}\RaggedRight #2\vspace{4pt}}}

Citation Handling

Two modes, set with --cite:

bibtex (default)

Keeps BibTeX keys in the text: \cite{key2020}. By default reads citation keys from a references section or bibliography file. Any [N] style citation placeholders are left as-is unless --cite-map is provided.

inline

Embeds \begin{thebibliography}...\end{thebibliography} with hand-written entries. Use with --biblio references.tex to supply the bibliography content.

Advanced Options

--title "Paper Title"     Override document title (default: first # heading)
--author "Name"           Author name
--affiliation "Univ"      Author affiliation
--email "[email protected]"      Corresponding email
--abstract                Extract abstract from ## Abstract section (default: auto)
--no-abstract             Skip abstract extraction
--appendix-appendix.md    Convert appendix as supplemental material
--suppress-numbers       Use \section*{} (unnumbered, for supplemental material)
--cite-map map.json      JSON mapping of citation placeholders to BibTeX keys
--compile                Run pdflatex twice after generation
--fig-dir figures/       Directory to copy figures from (default: auto-detect)
--help                   Show full usage

Compilation Hints

After generating .tex files, compile with:

# REVTeX (requires revtex4-2.cls installed)
cd output/ && pdflatex main.tex && pdflatex main.tex

# IEEEtran (requires IEEEtran.cls installed)  
cd output/ && pdflatex main.tex && pdflatex main.tex

The script auto-detects figures referenced in the markdown and copies them from the source directory to the output directory.

Limitations

• Not a general-purpose converter: Designed for academic paper structure (IMRaD + supplemental). Complex nested lists, code blocks, and footnotes may need manual adjustment.
• Pipe tables only: HTML <table> tags are not converted.
• Single-level bullets: Currently handles 2-level nesting; deeper lists may be flattened.
• Math environments: \begin{aligned}...\end{aligned} etc. pass through unchanged — ensure they are valid LaTeX.
• Citation conversion: [N] to \cite{} requires a user-provided mapping file or manual post-processing.
• No live-reload: Regenerate .tex after each .md edit; the skill does not watch files.

For Obsidian-style PDF rendering (A4, Arial, MathJax), use the obsidian-pdf skill instead.