前言
在前端开发中，文档编写是一个必不可少的环节。然而，对于那些对文档不太擅长但却对代码很熟悉的程序员来说，编写文档常常会成为一道难题。针对这个问题，微软开发了一个非常有用的 npm 包：@microsoft.azure/literate。
本文为大家介绍如何使用 @microsoft.azure/literate 来快速地生成美观而详细的文档。
安装
首先，我们需要在本地安装 @microsoft.azure/literate。可以通过以下命令进行安装：
npm install -g @microsoft.azure/literate
简要介绍
@microsoft.azure/literate 是一个基于 Markdown syntax、Code-literate Engine 技术开发的文档工具，它可以允许你使用 Markdown 语法直接嵌入代码块，并自动使用该代码的注释来生成文档。这使得文档编写更为简单，也能减少因文档与代码不一致而导致的问题。
而且，@microsoft.azure/literate 还为我们提供了很多丰富的功能，如自动生成文档的目录、代码高亮和文件转储，使得文档更为美观易于阅读。
如何使用
下面，我们就来详细了解如何使用 @microsoft.azure/literate。
创建工程
首先，我们需要在本地创建一个 @microsoft.azure/literate 工程。我们可以在任意目录下创建一个新的目录作为我们的文档工程目录，然后使用以下命令来初始化我们的工程。
literate init
该命令将会提供一些基本的配置，如文档文件夹名（document by default）和文档启动地址（docs by default）。根据自己的需要进行配置即可。
添加文档
当我们初始化好了我们的工程之后，我们需要向工程中添加文档文件。我们可以通过两种方法来添加文档。
方法一：手动添加
我们可以在文档目录下新建一个 Markdown 文件，比如 test.md。在该文件开头，添加以下注释:
<!-- @document -->
接下来，我们就可以在 test.md 中直接添加我们的代码块和文本了。
-- -------------------- ---- ------- -- ------ ---------- ----- -- --------- -------- ----- - ------------------ -------- -
<!-- 以下是一段 HTML 代码 --> <div class="test"> <h1>这是一个标题</h1> <p>这是一段普通的文本。</p> </div>
好了，我们已经编写好了我们的文档。接下来通过以下命令，我们即可生成我们的文档：
literate build
然后，打开文档启动地址，即可看到我们的文档了。
方法二：自动添加
我们也可以通过以下命令，快速的自动生成文档文件，并将代码块和注释内容添加到文件中。
literate template <filename> [--type=<type>]
其中 <filename> 为文档文件名，--type 参数为文档类型。比如，我们可以按以下方式快速生成一份名为 demo.md 的文档文件。
literate template demo.md --type=js
生成的文档文件中将包含一些 Markdown 模板，以及与 type 类型相关的代码模板。
其他命令
除了上述两个命令外，@microsoft.azure/literate 还提供了一些其他的命令。
本地启动
我们可以通过以下命令，在本地启动文档站点，方便我们查看文档。
literate serve
该命令将启动一个本地服务器，并在默认的端口 4000 上提供文档站点。
构建发布
我们也可以通过以下命令，构建生成静态文档。
literate build [--out=<out>]
其中，--out 参数用于指定输出路径。
结论
通过本文，我们已经可以很好的了解如何使用 @microsoft.azure/literate 这个强大的文档工具来生成我们的文档。希望这篇文章能够对你有所帮助，让你能够更加轻松的编写出高质量的文档。
示例代码
以下为一个示例 demo.md：
-- -------------------- ---- ------- ---- --------- --- - --------- ------ ------------------------- -------- -- -------- ------------------ ---- ------- -- --- ----- -------- ----------- - ------------------- ----------- - ---------------
自动生成目录
@literate 工具会自动生成文档中的目录，使得文档更易于阅读。
添加新章节
我们可以轻松地添加新的章节和子章节，而不需要关心目录的更新。
编译之后，该文件将被转化为一个美观而带目录的静态文档网站。 > 来源：[JavaScript中文网](https://www.javascriptcn.com/post/600566b381e8991b448e2f95) ，转载请注明来源 [https://www.javascriptcn.com/post/600566b381e8991b448e2f95](https://www.javascriptcn.com/post/600566b381e8991b448e2f95)