在linux下预览markdown的方法，转换成html和pdf

背景

markdown是一种便于编写和版本控制的格式，但却不便于预览——特别是包含表格等复杂内容时，单纯的语法高亮是远远不够的——这样就不能边预览边调整内容，需要找到一种预览方法。

思路

linux下有个工具，叫pandoc，支持多种文档之间的转换，我们可以用它将md（markdown）文件转换成html，再用浏览器打开html文件来预览，内容调整完毕后，再用pandoc将md文件转换成pdf，最后发布出去。

实现方法

以这个md文件为例，我们要实现该文件的预览

# 通信协议的帧格式

## 读寄存器

### 主机发包格式

| preamble | read_reg  | reg_address |
| -------- | --------- | ----------- |
|   0x1b   |     0x01  |    0x08     |

### 主机收包格式

| reg_value    |
| --------     |
|   0x00010000 |

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

markdown转html

实现效果

使用以下脚本实现

#!/bin/sh
OF=/tmp/t.html
pandoc --metadata pagetitle="API Document" -f markdown -t html -c ~/bin/md.css -o $OF -s $1
firefox $OF
1
2
3
4

几点说明：

1. 首先要安装pandoc
2. firefox如果没预装就装一个，用于预览html文件内容
3. 需要提供一个渲染页面格式的css文件，不然表格都没边框，很难看。脚本里的md.css是我网上找的资源，附件里应该有

markdown转pdf

实现效果

使用以下脚本实现

#!/bin/sh
OF=/tmp/t.pdf
pandoc --pdf-engine=xelatex -V CJKmainfont="Noto Sans CJK SC" -V geometry="top=2cm, bottom=1.5cm, left=2cm, right=2cm" -f markdown -t latex -o $OF -s $1
evince $OF
1
2
3
4

几点说明：

1. 首先要确保pandoc已安装
2. 安装texlive、texlive-xetex、texlive-lang-chinese、fonts-noto-cjk等包，确保pdf的中文能识别，中文字体能显示。
   2.1 如果pandoc或xelatex报错，一般是前面的包还不完整，根据提示补充安装即可。
3. 如果系统没安装evince的话，安装上，用于预览pdf文件。

总结

虽然现在有很多markdown在线预览工具，但是如果你对保密有要求，或者不能访问互联网，那pandoc还是很有用的。
另外pandoc有很多命令示例，大家使用时可以参考。