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