Markdoc

这里是我们的文档处理系统仓库。

这里的「文档处理系统」最初是为了处理来自于「Merico 帮助系统」和「Merico 专家系统」的文档而开发的，当然现在不仅限于此，事实上，该文档处理系统从设计之初就被设计为无预设环境的独立系统。

我们的文档采用 Markdown 编写，然后提供了 Markdown 编译为 HTML 的功能，还提供了 HTTP API 来响应文档信息及文档内容。

上手

如果你要「编译文档」或者「启动文档服务器」或者「运行单元测试」，以下是先决条件：

• Node.JS >= 14.17
• 拉取完本仓库之后请在根目录执行 npm install

如果只是「编写文档」，则无需这么麻烦，有一个文本编辑器就可以了。

如何编写文档？

基本上，我们的文档采用 Markdown 编写，然后在此基础上对 Markdown 的语法进行了一些扩展。关于文档的语法规范设计请见初学者教程或者 Tutorial for beginners。

编写好 Markdown 文档后，根据不同的语言，将文档放置在对应文档源仓库的 md/zh/ 或 md/en/ 目录下即可。所谓文档源，就是指这些文档来自于哪里，比如目前我们有「帮系统文档源」，还有「专家系统文档源」。我们约定，文档的目录结构为 md/<lang>/<file> 三级，其中 md 表示 Markdown 文档库目录，<lang> 表示语言目录，<file> 表示 Markdown 文档。

显然，从全局来看，文档的完整目录结构为 <source>/md/<lang>/<file> 四级，其中 <source> 就是指文档源。当然，具体到某一文档源内，就只有 md/<lang>/<file> 三级了。

其中目录命名须遵循以下规范：

• 目录名字符仅支持 小写英文字母/-/_
• 目录名必须以 小写英文字母 打头，且不得以 - 或 _ 结尾

Markdown 文档的命名须遵循以下规范：

• 文件名字符仅支持 小写英文字母/数字/-/_
• 文件名必须以 小写英文字母 打头，且不得以 - 或 _ 结尾
• 文档格式的后缀为 .md

特别的，我们还支持在 Markdown 文档的文件名中使用 @ 字符后跟数字 来表示文档版本，具体说明可见文档版本设计说明。

如何编译文档并预览？

如果想查看 Markdown 文档转换后的 HTML 文档效果，首先我们需要做一些配置，好让编译程序知道接下来要处理来自于哪里的 Markdown 文档。

由于我们的程序会接收来自多个不同数据源的文档，所以程序必须知道文档源的信息，故而每个文档源如果想被程序正常加载就必须正确配置自己的 md.yaml，程序在启动时会读取对应的配置信息，否则程序无法对其进行服务。注意，md.yaml 的位置与文档源仓库的 md 文件夹是平级的。本仓库默认也是一个文档源，同时也已经配置好了文档源信息，你可以点击这里查看配置格式。

确保所要编译的文档源的信息配置完成之后，我们需要在本仓库根目录创建一个名为 .env 的环境变量配置文件，其内容如下：

MARKDOWN_MANIFEST="manifest.yaml"

该环境变量指向 Markdown 文档源配置清单文件，配置清单里面记录了所需要的 Markdown 文档源的信息。同样，我们也已经配置好了一个示例清单供你开箱即用，你也可以替换为你自己的文档源配置清单文件。MARKDOWN_MANIFEST 环境变量指向的文件路径可以是绝对路径，也可以是相对于本仓库根目录的相对路径。

一言以蔽之，md.yaml 是放在文档源仓库下的，它指明了某个文档源自己是谁，manifest.yaml 是放在本文档处理系统仓库下的，它指明了我们要处理谁。之所以你看到本仓库里既有 manifest.yaml，又有 md.yaml，是因为本仓库既是文档处理系统，同时也是一个自包含的文档源，这些 Markdown 文档会被用作示例和测试。

最后运行以下命令：

npm run parse

该命令会读取 Manifest 中列出的所有文档源的 Markdown 文档，然后统一在 public/output/ 下生成对应的 HTML 文档，使用浏览器打开 HTML 文档即可预览。

如何启动一个 HTTP Server 来提供文档？

你也可以启动一个 Server 来通过 HTTP 协议向外提供文档，该 Server 会直接读取相关 Markdown 文档，然后按照指定参数返回文档信息和编译好的 HTML 内容（或内容片段）。

首先在 .env 文件中追加以下环境变量：

SERVER_HOST="localhost"
SERVER_PORT=3000

环境变量请根据你自己的实际情况来配置。当然，直接使用命令行来传入环境变量而不是配置 .env 也是可以的。如果你没有配置相关环境变量，服务器默认会在 localhost:3000 启动。关于完整的环境变量列表可见环境变量说明。

然后运行如下命令：

npm run serve

即可启动文档服务器。

你也可以在启动服务器时传入 BUILD_VERSION 和 BUILD_HASH 环境变量（或构建时动态写入到 .env 中），这样你可以通过相关 API 来获取服务器运行/构建时的版本信息。完整的服务器 API 可在 API 文档中找到。

如何运行单元测试？

在 .env 文件中追加以下环境变量：

TEST_SERVER_HOST="localhost"
TEST_SERVER_PORT=3001

正如前面我们提到过的，你也可以在运行时通过命令行传入相关的环境变量。但有一点要注意，如果你没有配置测试相关的环境变量，单元测试服务器默认会在 localhost:3000 启动。如果你还同时以默认配置启动了文档服务器，那么测试程序会因为端口冲突而无法正常启动。

然后运行如下命令：

npm run test

即可运行单元测试。