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