什么是 yocto-doc？
yocto-doc 是一个基于 Node.js 的 npm 包，能够根据 Markdown 文档自动生成漂亮的 HTML 文档。它适用于小型、中型项目的文档编写，可以为你的文档提供极大的便利。
安装 Yocto-Doc
安装 Yocto-Doc 非常简单，只需在命令行中执行以下指令即可：
npm install yocto-doc -g
上述指令将全局安装 yocto-doc。
如何使用 yocto-doc？
使用 yocto-doc，需要满足以下几个条件：
所有文档均放置在同一个目录下；
文档名称必须以“*.md”结尾；
在文档开头，必须添加以下标签：
<!-- title: 文档的标题 description: 文档的简要描述 -->
在该标签下，还可以添加其他自定义属性，如：
<!-- title: 文档的标题 description: 文档的简要描述 language: 文档语言（默认：中文） -->
构建 HTML 文档
在满足上述条件的前提下，执行以下命令，即可将所有 Markdown 文档生成 HTML 文档：
yocto-doc build ./docs
上述命令将会将 ./docs 目录下的所有 Markdown 文档转换成 HTML，并输出到 ./docs/_site 目录中。
编写自定义主题
yocto-doc 内置了一套默认的主题，如果需要自定义文档的样式，只需要修改主题即可。
在满足上述条件的前提下，创建一个空节点项目，执行以下命令：
yocto-doc theme ./my-theme
上述命令会在当前目录下创建一个名为 my-theme 的目录，其中包含主题的一些样式和模板文件。
自定义属性
你还可以为文档添加自定义属性，如：
<!-- title: 文档的标题 description: 文档的简要描述 language: 文档语言（默认：中文） content_type: 内容类型（默认：article） -->
给代码添加高亮
yocto-doc 内置了 Markdown 的语法高亮，只需要安装以下两个 npm 包即可：
npm install highlight.js npm install markdown-it-highlightjs
在 markdown 中添加代码块的方法如下：
```javascript
console.log("Hello World!")
```上述代码块将被转换为以下 HTML 代码：
<highlight>
<pre>
<code class="language-javascript">
console.log("Hello World!")
</code>
</pre>
</highlight>示例代码
接下来，让我们通过以下示例代码，演示如何使用 yocto-doc：
-- -------------------- ---- ------- ---- ------ --------- -- ------------ --------- ---- --------- -- --- - --------- -- ------------------- ---------- -- -- --------- -- --------- --------------------- ----- --- ------- --------- --
上述指令将全局安装 yocto-doc。
如何使用 Yocto-Doc？
一个文档需要满足以下几个条件才能够被 yocto-doc 处理：
- 所有文档均放置在同一个目录下；
- 文档名称必须以“*.md”结尾；
- 在文档开头，必须添加以下标签：
<!-- title: 文档的标题 description: 文档的简要描述 -->
构建 HTML 文档
在满足上述条件的前提下，执行以下命令，即可将所有 Markdown 文档生成 HTML 文档：
yocto-doc build ./docs
自定义属性
你还可以为文档添加自定义属性，如：
<!-- title: 文档的标题 description: 文档的简要描述 language: 文档语言（默认：中文） content_type: 内容类型（默认：article） -->
自定义文档主题
如果需要自定义文档主题，只需要执行以下命令：
yocto-doc theme ./my-theme
上述命令会在当前目录下创建一个名为 my-theme 的目录，其中包含主题的一些样式和模板文件。
总结
在这篇文章中，我们介绍了如何使用 yocto-doc，你可以在你的项目中使用它来生成漂亮的文档。
-- -------------------- ---- ------- -- -- ------------------ --- - --------- ------ ---- ------------- --------- ------------------------ ------------- - ------------------------------------------------------------------------------ -------- ------------------------------------------------------------------------------------------------------------------------