Markdown+Pandoc学术论文写作全攻略

1. 为什么选择Markdown+Pandoc写学术论文

十年前我第一次用Word写硕士论文时，被目录生成、图表编号和参考文献引用折磨得死去活来。直到发现Markdown+Pandoc这个组合，才真正体会到什么叫做"专注内容本身"。这个方案最吸引人的三点在于：

1. 纯文本的可靠性：所有内容都是可版本控制的文本文件，再也不用担心.docx文件损坏
2. 格式分离的优雅：用Markdown专注写作，用Pandoc处理排版，用LaTeX渲染公式
3. 生态工具的丰富：VS Code+插件组合提供了媲美专业排版软件的体验

实测用这套工具链完成过3篇EI会议论文和1篇SCI期刊论文，连最挑剔的审稿人都没发现这不是用传统LaTeX写的。下面分享我的完整工作流。

2. 环境配置与工具选型

2.1 核心组件安装

bash复制# Pandoc核心引擎（建议用最新版）
choco install pandoc -y  # Windows
brew install pandoc     # MacOS
sudo apt install pandoc # Linux

# LaTeX引擎（选MiKTeX或TeX Live）
choco install miktex -y  # 小型安装包

注意：TeX Live完整安装需要5GB空间，学术写作建议安装完整版以获得所有宏包支持

2.2 VS Code插件组合

1. Markdown All in One：快捷键增强
2. Mermaid Preview：实时渲染图表
3. LaTeX Workshop：公式辅助
4. Pandoc Citer：参考文献管理

json复制// settings.json配置片段
{
  "mermaid-editor.previewBackgroundColor": "transparent",
  "latex-workshop.latex.recipes": [
    {
      "name": "pandoc",
      "tools": ["pandoc"]
    }
  ]
}

3. 论文核心元素实现

3.1 LaTeX公式支持

行内公式用$E=mc^2$，独立公式块：

markdown复制$$ 
\frac{\partial u}{\partial t} = \alpha \nabla^2 u
$$ 

通过YAML元数据指定数学渲染引擎：

yaml复制---
math: |
  \usepackage{amsmath}
  \usepackage{amssymb}
---

3.2 Mermaid图表绘制

markdown复制```mermaid
graph TD
  A[研究背景] --> B(问题提出)
  B --> C{方法论}
  C -->|实验法| D[数据采集]
  C -->|理论分析| E[模型构建]
```

技巧：用%%{init}%%配置主题色，使图表符合学术风格：

mermaid复制%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#f5f5f5'}}}%%
graph LR
  实验设计-->数据采集

3.3 参考文献管理

1. 创建refs.bib文件存放BibTeX条目
2. 在Markdown中引用：[@smith2020]
3. 编译时添加参数：

bash复制pandoc paper.md --filter pandoc-citeproc --bibliography=refs.bib -o paper.pdf

4. 完整论文模板解析

yaml复制---
title: "基于深度学习的图像分割方法研究"
author: 
  - 张三
  - 李四
date: "2023-07-15"
abstract: |
  本文提出了一种新型...
keywords: [图像分割, 深度学习, 医学图像]
geometry: "left=3cm,right=2cm,top=2.5cm,bottom=2.5cm"
fontsize: 12pt
linestretch: 1.5
header-includes:
  - \usepackage{graphicx}
  - \usepackage{subcaption}
bibliography: refs.bib
csl: chinese-gb7714-2005-numeric.csl
---

5. 编译与排错指南

5.1 多格式输出命令

bash复制# 输出PDF（需LaTeX环境）
pandoc paper.md -o paper.pdf --template=eisvogel

# 输出Word（保留格式）
pandoc paper.md -o paper.docx --reference-doc=template.docx

# 输出HTML幻灯片
pandoc slides.md -t revealjs -o slides.html -s -V theme=white

5.2 常见错误排查

1. 公式不渲染：

   • 检查是否安装完整LaTeX
   • 添加--pdf-engine=xelatex参数

2. 参考文献缺失：

   • 确认.bib文件路径正确
   • 更新pandoc-citeproc版本

3. 中文乱码：

   yaml复制header-includes:
     - \usepackage{ctex}
   

6. 进阶技巧与优化

6.1 自定义模板修改

下载eisvogel模板后：

latex复制% 修改templates/eisvogel.tex
\definecolor{titlepagecolor}{cmyk}{1,.60,0,.40} % 修改标题页颜色
\setmainfont{Source Han Serif SC} % 设置中文字体

6.2 自动化脚本示例

python复制# build.py
import os
import subprocess

def compile_paper():
    cmd = [
        "pandoc",
        "paper.md",
        "-o", "paper.pdf",
        "--template=eisvogel",
        "--pdf-engine=xelatex",
        "--filter", "pandoc-crossref",
        "--bibliography=refs.bib"
    ]
    subprocess.run(cmd)

if __name__ == "__main__":
    compile_paper()

这套工作流最大的优势在于可复现性——所有格式控制都通过文本文件定义，再也不用担心换电脑后格式错乱。我实验室现在所有研究生论文都采用这个方案，配合Git版本控制，连导师都能轻松参与修改。