近期想要将一些技术文档放到云上托管，因此去了解了一下各类静态网页生成器以及部分使用细节，对此做了一些记录，希望能帮助到大家，后续也会更新一些关于云文档搭建的文章。
目前我们对云文档托管的需求如下：
根据以上需求，我们筛选出了以下三个网页生成器，并分析它们的优缺点，确定基于什么框架实现。
示例参考：VuePress 云文档。
VuePress 是一个极简静态网页生成器，简洁明了，新能高，以 Markdown 文档为中心，可使用 Vue 组件来实现扩展功能。
效果如图：
优缺点：
运行环境：
示例参考：LVGL 云文档
Sphinx 是一个功能强大的文档生成器，最初为生成 Python 文档而诞生，默认使用 reStructuresText（简称 rst）格式进行写作。
效果如图：
优缺点：
运行环境：
示例参考：TouchGFX 云文档
Docusaurus 与 VuePress 极为相似，环境配置以及功能都差不多，区别在于 Docusaurus 基于 React 构建，VuePress 基于 Vue 构建。
备注：如果想要基于 Python 构建的静态网页生成器，可以使用 MkDocs，其功能也是类似的。
效果如图：
运行环境：
备注：由于公司电脑安装了绿色版的 nodejs，版本为 10.15.3，因此暂未测试，但看了官方文档，操作基本与 VuePress 一致。
结合本章节开始提出的需求，结论如下：
此处选用 VuePress 作为网站生成器，拟采用下文中介绍 Pandoc+TeXLive 的方案实现 Markdown 转 PDF。
npm install -D vuepress-plugin-fulltext-search
module.exports = {
// ...
plugins: ['fulltext-search']
}
例如，命中文字高亮红色：
.search-box .suggestion a .suggestion-row .suggestion-content .highlight
color: red;
或者，命中文字高亮蓝色，背景色拿瓦白：
.search-box .suggestion a .suggestion-row .suggestion-content .highlight
color: blue;
background-color: NavajoWhite;
备注：可查阅全局搜索插件的 style 文件，搜索 highlight 研究搜索框的样式。
效果如图：
优缺点：
npm install -D vuepress-plugin-flexsearch
module.exports = {
// ...
plugins: [
['flexsearch'],
// 其他插件
]
}
效果如图：
优缺点：
【使用要求】
【使用步骤】：
module.exports = {
themeConfig: {
algolia: {
apiKey: '请看邮箱',
indexName: '请看邮箱'
}
}
}
【Algolia DocSearch 原理】：
Algolia 服务器会定期抓取我们填写的 云文档地址 中的内容进行分析并建立索引，这样在网站搜索框中输入关键词后，前端会调用 Algolia DocSearch 的接口并显示搜索结果。这些请求、结果显示的相关逻辑都封装好了，我们要做的就是按要求插入代码、配置好网站样式以及搜索框。
备注：根据 Algolia DocSearch 的官方文档，默认情况下它通常一周爬取一次网站内容，用户也可自行触发爬取，详见：DocSearch 的快速描述。
【支持的网站生成框架】：
VuePress 云文档 效果如图：
TouchGFX 云文档 效果如图：
优缺点：
综上所述，fulltext-search 插件的效果与 Algolia DocSearch 类似，因此在离线预览时，采用 fulltext-search，等到网站稳定发布时可以再考虑申请使用 Algolia DocSearch 提高检索效果。
基本原理：
优缺点：
安装 mdpdf：
npm install -g mdpdf
转换文档：
mdpdf README.md
其他相关设置参数详见：mdpdf。
优缺点：
与 mdpdf 类似，但效果要比 mdpdf 好，代码高亮且自动换行，表格也不会被遮挡，但表格没有划线，而且也没有目录，具体详见：markdown-pdf。
Pandoc 用于各种格式文档的转换，此处通过它将 Markdown 文档转化为 PDF 文件，其中包含以下两个步骤：
环境安装：
pandoc -v
tex -v
latex -v
xelatex -v
pdflatex -v
Pandoc 默认使用的 pdflatex 渲染引擎无法处理 Unicode 字符，如果 Markdown 中包含中文，转换为 PDF 的过程中会报错，需要用 xelatex 渲染引擎来处理中文，并且使用 CJKmainfont 选项指定支持中文的字体。
在 Windows 中，对于 Pandoc 2.0 以上版本，生成 PDF 文件的命令如下：
pandoc --pdf-engine=xelatex -V CJKmainfont="Microsoft YaHei" README.md -o README.pdf
CJKmainfont 指定支持中文的字体名称，寻找这些字体首先需要知道 language code，比如中文的是 zh，然后使用以下命令查看系统中支持该语言的所有字体：
fc-list :lang=zh
备注：fc-list 在Unix系统一般会预装，其他平台需要自行搜索安装依赖包，在 Windows 中可以直接查看 C:\Windows\Fonts 目录。
- Win7 可以访问：控制面板\所有控制面板项\字体。
- Win10 可通过【设置】=>【个性化】=>【字体】查看字体名称。
更多相关信息以及使用技巧详见：pandoc-markdown-with-chinese。
优缺点：
Sphinx 和 Pandoc + TeXLive 本质上原理一样，都是先转换为 LaTex 源文件，再渲染成 PDF，区别是使用的渲染引擎不太一样。
如果使用其他网页生成器，考虑到环境配置与灵活性的问题，综合考虑 Pandoc + TeXLive 更好一些。
| 关键需求点 | 选择方案 |
|---|---|
| 网页生成框架 | VuePress |
| 全文搜索插件 | 内部预览采用 fulltext-search 插件，正式上线再考虑是否改用 Algolia DocSearch |
| 生成 PDF | Pandoc + TeXLive，需要学习 LaTex 语法，以便调整 PDF 效果 |
VuePress 默认主题首页排版比较简洁，可能不太适用我们自身的情况，但可以通过自定义首页来解决这个问题，实际上就是开发一个 Vue 组件，需要编写 .vuepress/theme/components/Home.vue。
此外，直接编写静态首页也可以达到类似的效果。
参考示例：VuePress开发静态博客。
采用 VuePress 导航栏提供的列表功能即可，不同文档放在不同路径且展示在不同页面。
目前已知可将不同版本的文档放在不同文件路径下实现这个功能，后续需要测试一下放在 GitHub 的不同分支能否实现该功能，如果能用分支储存则用分支，减少 master 分支的文档内容，也方便归档整理。
上面选用了 Pandoc 作为 Markdown 转 PDF 的工具，该工具也可将 Word 转 Markdown，默认情况下，文本转换效果不错，但图片、代码、表格等特殊格式仍要手动调整校对一下。
例如，此处将 README.docx 转成 README.md，命令如下：
pandoc --extract-media ./images README.docx -o README.md
备注：其中 --extract-media 参数表示图片存放路径。