laurigates/docs-latex

Markdown to LaTeX Conversion

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

When to Use This Skill

| Use this skill when... | Use another skill when... | |------------------------|--------------------------| | Converting Markdown to presentation-quality PDF | Writing Markdown documentation (/docs:generate) | | Creating reports with diagrams and visualizations | Simple text formatting | | Generating print-ready strategic documents | Creating HTML documentation | | Building lifecycle reports with charts and timelines | Syncing existing docs (/docs:sync) |

Context

• Current directory: !pwd
• Available .md files: !find . -maxdepth 2 -name '*.md' -not -name 'CHANGELOG.md' -not -name 'README.md'

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

Execute this Markdown-to-LaTeX conversion workflow:

Step 1: Analyze the Markdown source

Read the source Markdown file and extract:

• Document title and metadata
• Section hierarchy (map # levels to LaTeX chapters/sections)
• Tables, lists, code blocks, callout blocks, and blockquotes
• Priorities or status indicators for color-coded markers
• Numerical data suitable for visualization

Step 2: Generate the LaTeX document

Create a .tex file adjacent to the source. Use the document preamble, color definitions, custom environments, and conversion rules from REFERENCE.md.

Apply the Markdown-to-LaTeX conversion rules:

| Markdown | LaTeX | |----------|-------| | # Title | \chapter{Title} | | ## Section | \section{Section} | | ### Subsection | \subsection{Subsection} | | **bold** | \textbf{bold} | | *italic* | \textit{italic} | | `code` | \texttt{code} | | - item | \begin{itemize}\item ...\end{itemize} | | 1. item | \begin{enumerate}\item ...\end{enumerate} | | > quote | \begin{tcolorbox}...\end{tcolorbox} | | [text](url) | \href{url}{text} | | Tables | booktabs tables with \toprule, \midrule, \bottomrule | | Code blocks | \begin{lstlisting}...\end{lstlisting} | | - [ ] / - [x] | $\square$ / $\boxtimes$ (requires amssymb) |

Step 3: Add visualizations (when --visualizations or data suggests it)

Choose appropriate TikZ/PGFPlots visualizations based on document content. Use the visualization templates from REFERENCE.md:

• Timeline for roadmaps with phases
• Bar/pie charts for release or metric data
• Risk matrix for documents with risk/impact data
• Test pyramid for QA/testing documents

Step 4: Compile to PDF

1. 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
   

2. Compile with two passes for cross-references:

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

3. If compilation fails, check REFERENCE.md for common compilation fixes.

Step 5: Clean up repository artifacts

Add LaTeX build artifacts to .gitignore if not already present: *.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

| Context | Command | |---------|---------| | Check LaTeX installed | which pdflatex 2>/dev/null | | Quick compile | pdflatex -interaction=nonstopmode -halt-on-error FILE.tex | | Full compile (with TOC) | pdflatex -interaction=nonstopmode FILE.tex && pdflatex -interaction=nonstopmode FILE.tex | | Check PDF page count | pdfinfo FILE.pdf 2>/dev/null | | Check PDF file size | stat -f %z FILE.pdf 2>/dev/null | | Install toolchain | apt-get install -y texlive-latex-extra texlive-fonts-recommended texlive-fonts-extra texlive-science | | Errors only | pdflatex -interaction=nonstopmode FILE.tex 2>&1 |

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