Markdown与Pandoc：文档写作与格式转换
Markdown 的核心优势：纯文本、可版本控制（Git 追踪变更）、写作和排版分离。Pandoc 作为通用文档转换器，可将 Markdown 转为 PDF、Word、HTML、LaTeX、slide 甚至 EPUB。本文覆盖实验记录模板、Pandoc 模板定制、文献引用、代码高亮和交叉引用，实现从实验记录到学术报告的统一工作流。
实测环境：Debian 13，Pandoc 3.6.2，LaTeX（TeX Live 2024）。
1. 环境搭建
# 安装 Pandoc 和 LaTeX 引擎sudo apt install pandoc texlive-xetex texlive-latex-extra \ texlive-fonts-recommended texlive-lang-chinese -y
# 安装中文字体（如果系统没有）sudo apt install fonts-noto-cjk -y
# 验证pandoc --versionxelatex --version2. 生信实验记录 Markdown 模板
# 实验记录：RNA-seq 差异表达分析
**日期：** 2026-01-10**实验者：** 张三**项目：** BRCA 肿瘤 vs 癌旁**样本数：** 48 (24 tumor + 24 normal)
## 目的
鉴定 BRCA 肿瘤组织与配对癌旁组织之间的差异表达基因，为后续 WGCNA 和通路分析提供候选基因列表。
## 方法和参数
### 比对- 工具：STAR 2.7.11b- 参考基因组：GRCh38 (Ensembl release 113)- 参数：`--outFilterMultimapNmax 20 --alignSJoverhangMin 8`
### 定量- 工具：featureCounts (subread 2.0.6)- 注释文件：`Homo_sapiens.GRCh38.113.gtf`- 参数：`-p -B -C -s 2`
### 差异表达- 工具：DESeq2 (R 4.4.1, Bioconductor 3.19)- 模型：`~ batch + condition`- 显著性阈值：|log2FC| > 1, padj < 0.05
## 结果摘要
| 比较 | 上调 | 下调 | 总计 ||------|------|------|------|| Tumor vs Normal | 1,247 | 893 | 2,140 |
## 问题和备注
1. 样本 BRCA_T_07 的 RIN 值偏低 (5.2)，后续关注其是否偏离主成分。2. batch2 的测序深度显著高于 batch1，已在 DESeq2 模型中加入 batch 协变量。
## 下一步
- [ ] GSEA 通路富集分析- [ ] 与 TCGA-BRCA 公开数据比对验证这种纯文本格式的优势：可以用 Git 追踪每次修改、用 grep 搜索任何关键词、任何文本编辑器都能打开。
3. Pandoc 转换——核心命令
3.1 基础转换
# Markdown → HTMLpandoc report.md -o report.html --standalone
# Markdown → DOCX（Word）pandoc report.md -o report.docx
# Markdown → PDF（通过 LaTeX）pandoc report.md -o report.pdf --pdf-engine=xelatex
# Markdown → LaTeX（只生成 .tex，不编译）pandoc report.md -o report.tex
# Markdown → 幻灯片（reveal.js）pandoc slides.md -t revealjs -s -o slides.html3.2 带中文字体的 PDF
# 中文字体是 Pandoc 生成 PDF 最常见的坑pandoc report.md -o report.pdf \ --pdf-engine=xelatex \ -V mainfont="Noto Serif CJK SC" \ -V sansfont="Noto Sans CJK SC" \ -V monofont="Noto Sans Mono CJK SC" \ -V CJKmainfont="Noto Serif CJK SC"
# 或者用模板指定字体（推荐，见下文）3.3 代码块高亮
```bash# 比对命令STAR --genomeDir /opt/refs/GRCh38/star_index \ --readFilesIn sample_R1.fastq.gz sample_R2.fastq.gz \ --readFilesCommand zcat \ --outSAMtype BAM SortedByCoordinate \ --runThreadN 16 \ --outFileNamePrefix ./aligned/sample_```Pandoc 支持多种语法高亮风格：
# 查看可用高亮风格pandoc --list-highlight-styles
# 指定风格pandoc report.md -o report.pdf --highlight-style=tango3.4 数学公式——LaTeX 原生支持
在 Markdown 里写 LaTeX 公式，Pandoc 直接渲染：
差异表达分析中，DESeq2 使用负二项分布建模：
$$K_{ij} \sim \text{NB}(\mu_{ij}, \alpha_i)$$
其中 $K_{ij}$ 是基因 $i$ 在样本 $j$ 中的计数，$\mu_{ij}$ 是期望值，$\alpha_i$ 是离散度参数。fold change 的收缩估计为：
$$\beta_i^{\text{MAP}} = \arg\max_{\beta} \left[ \log L(\beta | K_i) + \log p(\beta) \right]$$渲染结果和 LaTeX 原生一致，写分析报告时可以直接嵌入统计模型的公式。
4. 文献引用——生信报告必备
4.1 使用 BibTeX 引用
# 在 Markdown 里引用文献
差异表达分析使用 DESeq2 [@love2014] 进行，多重检验校正采用 Benjamini-Hochberg 方法 [@benjamini1995]。
# 参考文献准备一个 refs.bib 文件：
@article{love2014, title={Moderated estimation of fold change and dispersion for RNA-seq data with DESeq2}, author={Love, Michael I and Huber, Wolfgang and Anders, Simon}, journal={Genome biology}, volume={15}, number={12}, pages={1--21}, year={2014}, publisher={Springer}}
@article{benjamini1995, title={Controlling the false discovery rate: a practical and powerful approach to multiple testing}, author={Benjamini, Yoav and Hochberg, Yosef}, journal={Journal of the Royal statistical society: series B}, volume={57}, number={1}, pages={289--300}, year={1995}}编译命令：
pandoc report.md -o report.pdf \ --pdf-engine=xelatex \ --citeproc \ --bibliography=refs.bib \ -V mainfont="Noto Serif CJK SC"# --citeproc 启用文献处理4.2 图片交叉引用
# 需要 pandoc-crossref 过滤器sudo apt install pandoc-crossref -y{#fig:pca width=80%}
如 {@fig:pca} 所示，肿瘤和正常样本在第一主成分（PC1，解释 42% 方差）上清晰分离。编译时加 --filter pandoc-crossref：
pandoc report.md -o report.pdf --pdf-engine=xelatex --filter pandoc-crossref5. 定制 Pandoc 模板
5.1 创建生信报告模板
# 查看默认 LaTeX 模板pandoc -D latex > bioinfo-template.tex在默认模板基础上修改——加实验室 Logo、页眉页脚、自定义标题页。然后用：
pandoc report.md -o report.pdf \ --pdf-engine=xelatex \ --template=bioinfo-template.tex \ -V mainfont="Noto Serif CJK SC"5.2 YAML 元数据——文档信息集中管理
在 Markdown 文件头部写 YAML 元数据，Pandoc 会自动提取：
---title: "BRCA RNA-seq 差异表达分析报告"author: "张三"date: "2026-01-12"institute: "XX 大学生物信息学实验室"abstract: "本研究对 24 对 BRCA 肿瘤-癌旁组织进行 RNA-seq 分析，识别出 2,140 个差异表达基因（|log2FC| > 1, padj < 0.05）。"keywords: [BRCA, RNA-seq, 差异表达, DESeq2]toc: truetoc-depth: 2numbersections: true---编译后自动生成标题页、目录、章节编号。
6. 批量处理——分析报告自动化
生信流程跑完后自动生成报告：
#!/bin/bash# auto_report.sh —— 分析跑完后自动生成 PDF 报告
set -euo pipefail
PROJECT_DIR="$1"REPORT_TEMPLATE="${PROJECT_DIR}/docs/report_template.md"REPORT_OUT="${PROJECT_DIR}/results/analysis_report.pdf"REF_BIB="${PROJECT_DIR}/docs/refs.bib"FIG_DIR="${PROJECT_DIR}/results/figures"
# 1. 自动更新报告中的统计数字sed -i "s/{{TOTAL_DEGS}}/$(cat ${PROJECT_DIR}/results/degs_count.txt)/g" \ "${REPORT_TEMPLATE}"
# 2. 生成 PDFpandoc "${REPORT_TEMPLATE}" \ -o "${REPORT_OUT}" \ --pdf-engine=xelatex \ --citeproc \ --bibliography="${REF_BIB}" \ --filter pandoc-crossref \ --resource-path="${FIG_DIR}" \ -V mainfont="Noto Serif CJK SC" \ --toc \ --number-sections
echo "Report generated: ${REPORT_OUT}"7. 踩坑记录
坑1：中文 PDF 编译报错 “Missing character”。 默认 pdflatex 引擎不支持中文，必须用 --pdf-engine=xelatex 或 lualatex。同时确认系统中安装了中文字体包（fonts-noto-cjk 或 fonts-wqy-microhei）。
坑2：生信代码块的波浪线和反引号。 bash 代码里经常有 ${VAR} 这样的语法，在 Markdown 里写反引号代码块时注意用四个反引号（````）包裹含三个反引号的代码。或者干脆所有代码块都用四个反引号，免得出问题。
坑3：Pandoc 表格不支持合并单元格。 Markdown 表格本身是简化版的，不支持 rowspan/colspan。如果需要复杂表格，直接用 LaTeX 的 tabular 环境嵌在 Markdown 里，Pandoc 会透传。
坑4：DOCX 输出的样式丑得没法看。 Pandoc 默认 DOCX 样式非常基础。用 --reference-doc 指定一个样式模板：先 pandoc -o template.docx --print-default-data-file reference.docx，在 Word 里修改样式后，再 pandoc report.md -o report.docx --reference-doc=template.docx。
坑5：文献引用不生效。 检查三个点：① BibTeX 文件编码是 UTF-8，② 引用 key 拼写一致（大小写敏感），③ --citeproc 参数是否加了。另外确认 pandoc-citeproc 已正确安装。
坑6：--resource-path 设错导致图片找不到。 如果 Markdown 里写 ，且 --resource-path=results，那 Pandoc 会找 results/figures/pca.png。路径拼接逻辑有时不直观，建议用绝对路径或相对于 Markdown 文件的位置。
本文于 2026-01-12 在 Debian 13 上实测。
文章分享
如果这篇文章对你有帮助，欢迎分享给更多人！