前言
在前端开发中，我们经常需要生成文档以便于协作和沟通，也需要自动生成 API 文档以便于后续的维护。这时候，我们就需要用到一些工具来帮助我们完成这些任务。其中，dgeni-front-matter 就是一个非常好用的 npm 包，它可以帮助我们生成文档。
安装
使用 npm 安装 dgeni-front-matter
npm install dgeni-front-matter --save-dev
使用教程
配置
首先，我们需要在我们的项目中创建一个 dgeni.conf.js 文件并进行一些配置。以下是一个简单的配置示例：
-- -------------------- ---- -------
--- ----- - -----------------
--- -------- - -
--------------------------------
------------------------------
--
--- ----- - --- ----------------
-------------- - ------------------------ ------- -
--------------------------- - -----
--------------------------- - -----
----------------------- - ------
----------------------------------------- -
-------- ----
------------ -
-
-------- ------------
--------- -------
----------- -----------------
-
--
------------- -------
----- -
------ ------
---- -----
-
---
---以上配置中，我们使用了 dgeni-packages/ngdoc 和 dgeni-front-matter 两个包，并设置了 dgeni-front-matter 的基本配置。具体配置如下：
baseDir：markdown 文件相对路径的根目录。sourceFiles：markdown 文件的配置数组。include：markdown 文件的 glob 模式（匹配 markdown 文件相对路径）。basePath：markdown 文件所在目录的相对路径。fileReader：markdown 文件阅读器。
metadataFile：yaml 文件的类型。yaml：yaml 文件的配置，用于找到文本块的开始和结束标记。
创建 markdown 文件
在项目的某个目录下创建一个 markdown 文件，例如 docs/test.md。修改其内容如下：
-- -------------------- ---- ------- --- ------ ---- -------- ----- ---------- ----- ------------------- -------- --- - ---- -------- ---- -- - ---- ---------
注意，这个 markdown 文件需要以 --- 开始和结束，中间的内容会被当作文本属性。我们在中间部分添加了 title、date、tags 三个属性并赋值。
生成文档
执行以下命令来生成文档：
dgeni
在执行完毕后，会生成一个文档目录 docs/partials 和一个配置文件 docs/dgeni.json。其中，文档目录中的文件就是生成的文档页面，而配置文件中则包含了文档的一些基本信息。
使用文档
在你的项目中引入生成的文档，即可使用它们。
-- -------------------- ---- -------
--------- -----
----- ----------
------
----- ----------------
--------- ---------------
----- ---------------- --------------- ------------------
-------
------
--------
------ ------------
-----
----
------ ----------------------------------- -----------------
-----
------
---------
------
---- ---- ------- ------- ---- ---- ---
-------
-------
-------在你的项目中插入一个链接，类似于 docs/partials/test.html，即可链接到生成的文档页面。你可以根据自己的需求来修改链接。
总结
在前端开发中，生成文档是一个比较重要的部分，dgeni-front-matter 可以帮助我们快速生成文档，大幅度提高我们的工作效率。希望此教程能够对你有所帮助。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/5f144500403f2923b035c2e7