云文档托管方案分析

一、前言

近期想要将一些技术文档放到云上托管，因此去了解了一下各类静态网页生成器以及部分使用细节，对此做了一些记录，希望能帮助到大家，后续也会更新一些关于云文档搭建的文章。

二、网页生成器的选择

目前我们对云文档托管的需求如下：

1. 要将一些 Markdown 说明文档、帮助文档托管到云端，确定是用网页的方式展现，类似的可以参考：Vue 云文档、LVGL 云文档、TouchGFX 云文档；
2. 网页需要有导航栏、搜索栏、侧边栏；
3. 主页与导航栏需要列处文档列表，即需要能够自定义主页和导航栏；
4. 搜索栏可以搜索文档标题也可以进行全局搜索；
5. 需要可以选择文档版本，可以考虑将版本列表放到导航栏。
6. 需要能将 Markdown 文档转为 PDF，方便下载浏览。

根据以上需求，我们筛选出了以下三个网页生成器，并分析它们的优缺点，确定基于什么框架实现。

2.1 VuePress

示例参考：VuePress 云文档。

VuePress 是一个极简静态网页生成器，简洁明了，新能高，以 Markdown 文档为中心，可使用 Vue 组件来实现扩展功能。

效果如图：

优缺点：

1. 环境配置简单，配置操作简单。
2. 提供默认主题，可自定义主题，从而更改网站主页与整体样式。
3. 支持导航栏、侧边栏、搜索栏，提供内置搜索引擎，但无法搜索全文。
4. 以 Markdown 为中心开发，内置 md 扩展功能与 Vue 扩展功能。
5. 支持全文搜索插件，并支持内置 Algolia DocSearch。
6. 支持内置多语言翻译。

运行环境：

1. Node.js >= 8.6。

2.2 Sphinx

示例参考：LVGL 云文档

Sphinx 是一个功能强大的文档生成器，最初为生成 Python 文档而诞生，默认使用 reStructuresText（简称 rst）格式进行写作。

效果如图：

优缺点：

1. 具有丰富的输出格式，支持 HTML、LaTeX（用于打印 PDF 版本）、manual pages、纯文本等。
2. 具有完备的交叉引用，语义化标签，可以自动化链接函数、类、引文、术语及相似的片段信息。
3. 使用 rst 作为标记语言，可以享有 docutils 为其提供的分析、转换等多种工具，转换为 PDF 文档较为方便。
4. 自带的搜索框支持全文搜索，但搜索界面不太好用，且 Algolia DocSearch 不支持该生成器，生成网页后，需要手动嵌入 DocSearch 的代码。
5. 不支持 Markdown 文档，需要借助 Recommonmark 插件将 md 文档转为 rst 格式。
6. 不支持导航栏，需手动改写静态网页。
7. 环境配置相较于 VuePress 和 Docusaurus 来讲过于复杂，由于公司电脑无法使用 pip 安装依赖包，暂时无法测试。

运行环境：

1. python 2.4 或 python 3.1，以及 docutils 和 jinja2 库，sphinx 必须在 0.7 版本。
2. 如果需要源码支持高亮显示，则必须安装 pygments 库。
3. 如果使用 Python 2.4，还需要 uuid 库。

2.3 Docusaurus

示例参考：TouchGFX 云文档

Docusaurus 与 VuePress 极为相似，环境配置以及功能都差不多，区别在于 Docusaurus 基于 React 构建，VuePress 基于 Vue 构建。

备注：如果想要基于 Python 构建的静态网页生成器，可以使用 MkDocs，其功能也是类似的。

效果如图：

运行环境：

1. Node.js >= 12.13.0。

备注：由于公司电脑安装了绿色版的 nodejs，版本为 10.15.3，因此暂未测试，但看了官方文档，操作基本与