====== 使用markdown编辑生成技术文档 ======

===== markdown概述 =====

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

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

Markdown语法参见：[[https://coding.net/help/doc/project/markdown.html|Markdown语法介绍（Coding）]]、[[https://www.jianshu.com/p/191d1e21f7ed|Markdown基本语法（简书）]]
===== 环境安装 =====

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

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

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

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

  * sublime
  * remarkable
  * markdownpad
  * Typora
  * ……

IDE环境：

  * idea: 可以安装[[https://plugins.jetbrains.com/plugin/7896-markdown-navigator|markdown-navigator插件]]或者[[https://plugins.jetbrains.com/plugin/7793-markdown|markdown插件]]
  * eclipse： 安装[[https://marketplace.eclipse.org/content/markdown-text-editor|markdown-text-editor插件]]
  * vscode: 安装[[https://code.visualstudio.com/docs/languages/markdown|markdown插件]]

==== 文档生成环境 ====

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

=== pandoc的安装 ===

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

  * Windows下的安装：下载[[https://github.com/jgm/pandoc/releases|安装包]]直接安装即可
  * Linux下的安装：Pandoc已经包含在大部分Linux发行版的官方仓库中，直接使用诸如apt/dnf/yum/pacman之类的安装工具直接安装即可
  * MacOS下的安装：建议通过HomeBrew进行安装即可

> 详细的安装说明参见：[[https://pandoc.org/installing.html|官方安装文档]]

=== latex的安装 ===

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

  * windows环境：下载安装[[https://miktex.org/download|miktex]]，注意安装后需要再安装cjk，cjk-fonts等相关package
  * Linux环境：使用apt/dnf/yum/pacman等安装工具安装texlive、texlive-latex等相关软件包即
  * MacOS：使用HomeBrew安装texlive即可

===== 安装后的设置PDF文件生成 =====

==== 安装后的设置 ====

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

  * 下载[[https://github.com/Wandmalfarbe/pandoc-latex-template/releases|eisvogel模板]]
  * 将解压缩后的eisvogel.tex文件重命名为eisvogel.latex保存从到指定目录下
    * windows： C:\Users\USERNAME\AppData\Roaming\pandoc\templates
    * Linux/MacOS：~/.pandoc/templates/


==== PDF文件生成 ====

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

  * windows: pandoc -N -s %%--%%toc %%--%%pdf-engine=xelatex -V CJKmainfont=NSimSun -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信息 ====

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

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

上述文档设置说明：

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

> 更多设置参见[[https://pandoc.org/MANUAL.html#metadata-variables|pandoc官方文档]]和[[https://github.com/Wandmalfarbe/pandoc-latex-template|eipsvogel说明]]

==== 其他写作要求 ====

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

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

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

===== 示例 =====

==== markdown源文件 ====

<file markdown sample.md>
---
title: "示例文档"
subtitle: "示例文档子目录"
author: "jinlong.hao"
date: "2019-08"
titlepage: true
toc-own-page: true
secnumdepth: 5
...


# 文档概述

## 本文说明 

本文是markdown转换为pdf的示例文件，主要用于演示如何通过markdown转换为pdf文件

## 文档保密要求

本文无任何保密要求，任何和均可自由使用



# 内容示例

## 这是正文内容 

这是正文这是正文这是正文这是正文这是正文这是正文这是正文这是正文这是正文
这是正文这是正文这是正文这是正文这是正文这是正文这是正文这是正文这是正文
这是正文

这是正文这是正文这是正文这是正文这是正文这是正文这是正文这是正文这是正文
这是正文这是正文这是正文这是正文这是正文这是正文这是正文这是正文这是正文
这是正文这是正文


## 基本格式 

**加粗字体**

*斜体*

~~删除线~~

> 这是引用

## 分割线 

----

## 超链接 

[百度](http://www.baidu.com)

## 列表

### 有编码列表

1. 列表
2. 列表
   1. 列表
   2. 列表
1. 列表

### 无编号列表

* 编号
* 编号
* 编号
  * 编号
  * 编号
* 编号

## 表格

| 标题1  | 标题2 | 标题3 |
| ------ | ----- | ----- |
| 1      | aaa   | aaaaa |
| 2      | bbb   | bbbbb |


## 代码 

~~~ java
public static void main(){
   System.out.println("Hello, world!");
}
~~~

</file>


==== 生成的pdf文件 ====

生成的PDF文件为：{{others:markdown_sample.pdf|sample.pdf}}