在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 |

markdown转html

实现效果
md2html

使用以下脚本实现

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

markdown转pdf

实现效果
md2pdf
使用以下脚本实现

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

总结

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