Markdown to LaTeX Conversion

Convert Markdown documents to professional LaTeX with advanced typesetting, TikZ/PGFPlots visualizations, and PDF compilation.

When to Use This Skill

Context

• Source file exists: !test -f "$1" && echo "yes" || echo "no"
• LaTeX installed: !which pdflatex 2>/dev/null
• Current directory: !pwd
• Available .md files: !find . -maxdepth 2 -name '*.md' -not -name 'CHANGELOG.md' -not -name 'README.md' 2>/dev/null | head -10

Parameters

• <file>: Path to the Markdown source file (required)
• --no-compile: Generate .tex file only, skip PDF compilation
• --visualizations: Include TikZ/PGFPlots diagrams (timelines, charts, risk matrices)
• --report-type: Document structure preset
  • roadmap: Phase-based roadmap with timeline visualization
  • lifecycle: Project lifecycle with release charts and velocity graphs
  • general: Standard professional document (default)

Execution

Phase 1: Analyze Markdown Source

Read the source Markdown file and extract:

• Document title and metadata
• Section hierarchy (map # levels to LaTeX chapters/sections)
• Tables (convert to booktabs format)
• Lists (itemize/enumerate)
• Code blocks (lstlisting/minted)
• Callout blocks or blockquotes (map to tcolorbox environments)
• Priorities or status indicators (map to color-coded markers)
• Numerical data suitable for visualization

Phase 2: Generate LaTeX Document

Create a .tex file adjacent to the source with these components:

Document class and packages:

\documentclass[a4paper,11pt]{report}

% Core packages
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{lmodern}
\usepackage[margin=2.5cm]{geometry}
\usepackage{hyperref}
\usepackage{xcolor}
\usepackage{booktabs}
\usepackage{longtable}
\usepackage{enumitem}
\usepackage{fancyhdr}
\usepackage{titlesec}
\usepackage{tcolorbox}
\usepackage{fontawesome5}
\usepackage{amssymb}
\usepackage{graphicx}

% Visualization packages (when --visualizations)
\usepackage{tikz}
\usepackage{pgfplots}
\pgfplotsset{compat=1.18}
\usetikzlibrary{shapes,arrows,positioning,calc,patterns}

Color definitions:

\definecolor{critical}{HTML}{DC2626}
\definecolor{high}{HTML}{EA580C}
\definecolor{medium}{HTML}{CA8A04}
\definecolor{low}{HTML}{16A34A}
\definecolor{info}{HTML}{2563EB}
\definecolor{warning}{HTML}{D97706}
\definecolor{success}{HTML}{059669}

Custom environments:

\newtcolorbox{infobox}{colback=info!5,colframe=info,title=\faInfoCircle\ Info}
\newtcolorbox{warningbox}{colback=warning!5,colframe=warning,title=\faExclamationTriangle\ Warning}
\newtcolorbox{successbox}{colback=success!5,colframe=success,title=\faCheckCircle\ Success}

Header/footer setup:

\setlength{\headheight}{14pt}
\pagestyle{fancy}
\fancyhf{}
\fancyhead[L]{\leftmark}
\fancyhead[R]{\thepage}
\fancyfoot[C]{\small Document Title}

Markdown-to-LaTeX Conversion Rules

Priority/Status Color Mapping

Map status indicators found in the source to colored markers:

% Inline priority markers
\newcommand{\critical}{\textcolor{critical}{\faBolt\ Critical}}
\newcommand{\highpri}{\textcolor{high}{\faExclamationCircle\ High}}
\newcommand{\mediumpri}{\textcolor{medium}{\faMinusCircle\ Medium}}
\newcommand{\lowpri}{\textcolor{low}{\faCheckCircle\ Low}}

Phase 3: Add Visualizations (when –visualizations or data suggests it)

Choose appropriate visualizations based on document content:

Timeline (for roadmaps with phases):

\begin{tikzpicture}[scale=1.2]
  % Draw timeline arrow
  \draw[->,thick] (0,0) -- (12,0);
  % Phase markers
  \foreach \x/\label/\dates in {
    1.5/Phase 1/Q1,
    4.5/Phase 2/Q2,
    7.5/Phase 3/Q3,
    10.5/Phase 4/Q4} {
    \draw[thick] (\x,0.2) -- (\x,-0.2);
    \node[above] at (\x,0.3) {\textbf{\label}};
    \node[below] at (\x,-0.3) {\small\dates};
  }
\end{tikzpicture}

Bar/pie charts (for release or metric data):

\begin{tikzpicture}
\begin{axis}[
  ybar, bar width=15pt,
  xlabel={Category}, ylabel={Count},
  symbolic x coords={A,B,C,D},
  xtick=data, nodes near coords
]
\addplot coordinates {(A,10) (B,25) (C,15) (D,8)};
\end{axis}
\end{tikzpicture}

Risk matrix (for documents with risk/impact data):

\begin{tikzpicture}
  \fill[green!20] (0,0) rectangle (2,2);
  \fill[yellow!20] (2,0) rectangle (4,2);
  \fill[yellow!20] (0,2) rectangle (2,4);
  \fill[orange!20] (2,2) rectangle (4,4);
  \fill[red!20] (4,2) rectangle (6,4);
  % Labels and axes
\end{tikzpicture}

Test pyramid (for QA/testing documents):

\begin{tikzpicture}
  \fill[green!30] (-3,0) -- (3,0) -- (2,1.5) -- (-2,1.5) -- cycle;
  \node at (0,0.75) {\textbf{Unit Tests}};
  \fill[yellow!30] (-2,1.5) -- (2,1.5) -- (1,3) -- (-1,3) -- cycle;
  \node at (0,2.25) {\textbf{Integration}};
  \fill[red!30] (-1,3) -- (1,3) -- (0,4.5) -- cycle;
  \node at (0,3.5) {\textbf{E2E}};
\end{tikzpicture}

Phase 4: Compile to PDF

Install LaTeX toolchain if not available:

apt-get update && apt-get install -y texlive-latex-extra texlive-fonts-recommended \
  texlive-fonts-extra texlive-science latexmk

Compile with two passes for cross-references:

pdflatex -interaction=nonstopmode DOCUMENT.tex
pdflatex -interaction=nonstopmode DOCUMENT.tex

Two passes are required to resolve:

• Table of contents
• Cross-references (\ref, \pageref)
• Hyperlinks
• Page numbers in headers

Common compilation fixes:

Phase 5: Repository Cleanup

Add LaTeX build artifacts to .gitignore if not already present:

# LaTeX build artifacts
*.aux
*.log
*.out
*.toc
*.lof
*.lot
*.fls
*.fdb_latexmk
*.synctex.gz
*.bbl
*.blg
*.nav
*.snm
*.vrb

Post-actions

1. Report the output PDF path, page count, and file size
2. Summarize what visualizations were generated
3. List any compilation warnings that may need attention
4. Suggest the .gitignore additions if not already present

Agentic Optimizations

For detailed LaTeX patterns, TikZ templates, and package reference, see REFERENCE.md.