docs-latex

Markdown 转 LaTeX

将 Markdown 文档转换为专业的 LaTeX，包含高级排版、TikZ/PGFPlots 可视化和 PDF 编译。

适用场景

在以下情况下使用此技能……	在以下情况下使用其他技能……
将 Markdown 转换为适合演示的 PDF	编写 Markdown 文档（/docs:generate）
创建包含图表和可视化的报告	简单的文本格式设置
生成适合印刷的战略文档	创建 HTML 文档
构建包含图表和时间线的生命周期报告	同步现有文档（/docs:sync）

上下文

• 当前目录：!pwd
• 可用的 .md 文件：!find . -maxdepth 2 -name '*.md' -not -name 'CHANGELOG.md' -not -name 'README.md'

参数

• <file>：Markdown 源文件的路径（必需）
• --no-compile：仅生成 .tex 文件，跳过 PDF 编译
• --visualizations：包含 TikZ/PGFPlots 图表（时间线、图表、风险矩阵）
• --report-type：文档结构预设
  • roadmap：按阶段划分的路线图，包含时间线可视化
  • lifecycle：项目生命周期，包含发布图表和速度图
  • general：标准专业文档（默认）

执行

执行此 Markdown 到 LaTeX 的转换工作流：

第 1 步：分析 Markdown 源文件

读取 Markdown 源文件并提取：

• 文档标题和元数据
• 章节层级（将 # 层级映射到 LaTeX 章节/小节）
• 表格、列表、代码块、提示块和引用块
• 用于彩色标记的优先级或状态指示器
• 适合可视化的数值数据

第 2 步：生成 LaTeX 文档

在源文件旁创建 .tex 文件。使用 REFERENCE.md 中的文档序言、颜色定义、自定义环境和转换规则。

应用 Markdown 到 LaTeX 的转换规则：

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}
表格	使用 \toprule、\midrule、\bottomrule 的 booktabs 表格
代码块	\begin{lstlisting}...\end{lstlisting}
- [ ] / - [x]	$\square$ / $\boxtimes$（需要 amssymb）

第 3 步：添加可视化（在使用 --visualizations 或数据表明需要时）

根据文档内容选择合适的 TikZ/PGFPlots 可视化。使用 REFERENCE.md 中的可视化模板：

• 时间线：用于包含阶段的路线图
• 条形图/饼图：用于发布或指标数据
• 风险矩阵：用于包含风险/影响数据的文档
• 测试金字塔：用于 QA/测试文档

第 4 步：编译为 PDF

1. 如果尚未安装 LaTeX 工具链，请先安装：

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

2. 使用两次编译处理交叉引用：

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

3. 如果编译失败，请参阅 REFERENCE.md 中的常见编译问题修复方法。

第 5 步：清理仓库产物

如果 .gitignore 中尚未包含 LaTeX 构建产物，请添加：*.aux、*.log、*.out、*.toc、*.lof、*.lot、*.fls、*.fdb_latexmk、*.synctex.gz、*.bbl、*.blg、*.nav、*.snm、*.vrb。

后续操作

1. 报告输出 PDF 的路径、页数和文件大小
2. 概述生成的可视化内容
3. 列出可能需要处理的编译警告
4. 如果 .gitignore 中尚未包含相关条目，建议添加

面向 Agent 的优化

上下文	命令
检查是否已安装 LaTeX	which pdflatex 2>/dev/null
快速编译	pdflatex -interaction=nonstopmode -halt-on-error FILE.tex
完整编译（含目录）	pdflatex -interaction=nonstopmode FILE.tex && pdflatex -interaction=nonstopmode FILE.tex
检查 PDF 页数	pdfinfo FILE.pdf 2>/dev/null
检查 PDF 文件大小	stat -f %z FILE.pdf 2>/dev/null
安装工具链	apt-get install -y texlive-latex-extra texlive-fonts-recommended texlive-fonts-extra texlive-science
仅显示错误	pdflatex -interaction=nonstopmode FILE.tex 2>&1

如需了解详细的 LaTeX 模式、TikZ 模板和软件包参考，请参阅 REFERENCE.md。