Markdown是一种轻量级标记语言，创始人为约翰·格鲁伯（英语：John Gruber）。它允许人们“使用易读易写的纯文本格式编写文档，然后转换成有效的XHTML（或者HTML）文档”。这种语言吸收了很多在电子邮件中已有的纯文本标记的特性。

由于Markdown的轻量化、易读易写特性，并且对于图片，图表、数学式都有支持，当前许多网站都广泛使用 Markdown 来撰写帮助文档或是用于论坛上发表消息。例如：GitHub、reddit、Diaspora、Stack Exchange、OpenStreetMap 、SourceForge等。甚至Markdown能被使用来撰写电子书。

Markdown语法参见：Markdown语法介绍（Coding）、Markdown基本语法（简书）

Markdown写作生成环境包括写作环境和文档生成环境两部分：

• 写作环境主要用于书写markdown文件
• 文档生成环境主要用于实现markdown转换为pdf文档

Markdown的规范本身就是文本文档，故任何文本文件编辑器均可进行markdown文件的编辑，编辑markdown文件可以使用专业的编辑器，也可以在IDE环境中安装markdown的插件。

目前业内常用的markdown文件编辑器主要包括：

• sublime
• remarkable
• markdownpad
• Typora
• ……

IDE环境：

• idea: 可以安装markdown-navigator插件或者markdown插件
• eclipse： 安装markdown-text-editor插件
• vscode: 安装markdown插件

markdown生成pdf主要需要使用pandoc和latex(texlive/miktex)两个工具，具体安装方式如下：

Pandoc是由John MacFarlane开发的标记语言转换工具，可实现不同标记语言间的格式转换，堪称该领域中的“瑞士军刀”。Pandoc使用Haskell语言编写，以命令行形式实现与用户的交互，可支持多种操作系统。

• Windows下的安装：下载安装包直接安装即可
• Linux下的安装：Pandoc已经包含在大部分Linux发行版的官方仓库中，直接使用诸如apt/dnf/yum/pacman之类的安装工具直接安装即可
• MacOS下的安装：建议通过HomeBrew进行安装即可

详细的安装说明参见：官方安装文档

latex工具，在windows下建议安装miktex，Linux和MacOS下建议安装texlive

• windows环境：下载安装miktex
• Linux环境：使用apt/dnf/yum/pacman等安装工具安装texlive、texlive-latex等相关软件包即
• MacOS：使用HomeBrew安装texlive即可

为保证生成的pdf格式（自动插入封面、目录页、页眉页脚等信息），需要使用latex的template，具体使用方式是：

• 下载eisvogel模板
• 将解压缩后的eisvogel.tex文件重命名为eisvogel.latex保存从到指定目录下
  • windows： C:\Users\USERNAME\AppData\Roaming\pandoc\templates
  • Linux/MacOS：~/.pandoc/templates/

配置完成后即可在通过pandoc命令生成pdf文件：

• windows: pandoc -N -s –toc –pdf-engine=xelatex -V CJKmainfont='WenQuanYi Micro Hei' -V mainfont='WenQuanYi Micro Hei' -V geometry:margin=1in –template eisvogel –listings a.md -o a.pdf
• Linux/MacOS: pandoc -N -s –toc –pdf-engine=xelatex -V CJKmainfont='WenQuanYi Micro Hei' -V mainfont='WenQuanYi Micro Hei' -V geometry:margin=1in –template eisvogel –listings a.md -o a.pdf

上述命令中各个参数的说明：

• -N 给各个章节编码
• -s 添加页眉页脚
• –toc 包含目录
• –pdf-engine=xelatex 指定处理pdf的latex引擎
• -V CJKmainfont=“WenQuanYi Micro Hei” 指定亚洲字体为文泉驿微米黑
• -V mainfont=“WenQuanYi Micro Hei” 指定主要字体为文泉驿微米黑
• -V geometry:margin=1in 指定页边距
• –listings 对于code增加增加行号
• a.md 指输入文档为a.md文件
• -o a.df 指输出文件为a.pdf

注：考虑到上述命令过长，在Linux、MacOS下可以分别通过修改~/.bashrc、~/.bash_profile文件来设置alias，即可减少每次的输入

在每个markdown最前面增加metadata信息，metadata内容开始行内容为三个“-”，结束行为三个“.”，示例如下：

---
title: "示例文档"
subtitle: "示例文档子标题"
author: [jinlong.hao]
date: "2019-08"
titlepage: true
toc-own-page: true
secnumberdepth: 5
header-left: "示例文档子标题"
...

上述文档设置说明：

• title: 文档的标题
• subtitle：文档的子标题
• author：作者
• date: 创建日期
• titlepage: 是否创建封面页
• toc-own-page: 目录是否单独分页
• secnumberdepth：目录编号深度
• header-left：页眉左边显示内容，默认为title，此处设置为了修改为子标题

更多设置参见pandoc官方文档和eipsvogel说明

为保证markdown转pdf不报错，在编写markdown的时候有几个原则要求：

• 每个标题前后都必须有空行
• 每个表格前后都必须有空行
• 每个代码块前后收必须有空行
• 每个列表前后必须有空行

总而言之，每个不同的格式和内容前后都需要有空行

• 源文件
• 生成的PDF文件