在前端开发过程中，编写文档是一个非常重要的工作。好的文档可以帮助团队成员更快地理解和使用代码，也可以帮助新手快速上手。但是，编写文档需要投入大量的时间和精力，如果没有好的工具辅助，往往会比较痛苦。而 npm 包 markdown-documentation 就是这样一款工具，可以帮助我们更轻松地编写文档。本篇文章主要介绍如何使用该 npm 包。
安装
首先，我们需要安装 markdown-documentation。使用 npm 命令安装即可：
npm install markdown-documentation --save-dev
使用
接下来，我们就可以开始使用 markdown-documentation 了。markdown-documentation 包含两个核心功能：
- 自动生成 API 文档。
- 自动生成 README 文档。
自动生成 API 文档
我们可以使用 markdown-documentation 自动生成 API 文档。这需要我们在代码中使用特定的注释格式来标识 API，然后运行 markdown-documentation 工具生成文档。注释格式如下：
-- -------------------- ---- ------- --- - --------- ------------ - ------------ -------- ----------- - ------ ------ --------- - ----- ----------- - -------- ------ ------ ----------- -- -------- ----------------------- - -- -------- ---- -
这样，我们就定义了一个名为 functionName 的函数，并加入了注释。其中 @function 表示这是一个函数，@description 表示函数描述，@param 表示函数参数，@returns 表示函数返回值。
在代码中添加好注释后，我们可以使用如下命令来生成 API 文档：
npx markdown-documentation --input ./src --output docs/api.md
其中，--input 表示输入的目录，这里我们输入的是 ./src，即代码所在的目录。--output 表示输出的文件，这里我们输出到 docs/api.md。
自动生成 README 文档
markdown-documentation 还可以自动生成 README 文档。我们只需要在项目的根目录下创建一个名为 README.md.ejs 的文件，然后在文件中使用 EJS 模板语言编写文档即可。
下面是一个简单的示例：
# My Project <%= getBadges() %> ## Installation ```bash npm install my-project --save
Usage
const myProject = require('my-project')
myProject.helloWorld()API
<%= getApi('api.md') %>
其中，`getBadges()` 函数会自动生成项目的一些统计信息，`getApi('api.md')` 函数会自动引入我们上一步生成的 API 文档。
然后，我们就可以使用如下命令来生成 README 文档了：
npx markdown-documentation --readme ./README.md.ejs --output README.md
-- -------------------- ---- ------- -- ---------- --------------- ---------------------------- --------------- ------------ -- -- ---------------------- ------------------- ---------------------------------- --- --- ------ ------------------------------------- - ------------------------------------------------------------------------------ -------- ------------------------------------------------------------------------------------------------------------------------