在前端开发中，文档永远是一项不可或缺的工作。针对 TypeScript 项目，我们通常会使用 TypeDoc 来自动生成 API 文档。不过，官方提供的 HTML 格式有些不够灵活，如果想要将文档嵌入到项目的 README 中，或者发布到 GitHub Pages 中，那么我们就需要将文档转换成 Markdown 格式。而 typedoc-plugin-markdown 就是一个可以将 TypeDoc 生成的 JSON 数据转换成 Markdown 文件的 npm 包。
安装 typedoc-plugin-markdown
首先，我们需要在项目根目录下安装 typedoc-plugin-markdown：
npm install --save-dev typedoc typedoc-plugin-markdown
其中，typedoc 是 TypeDoc 本身的依赖，我们一起安装。
配置 TypeScript
在开始使用 typedoc-plugin-markdown 之前，我们需要确保 TypeScript 项目正确地配置了类型声明、tsconfig.json、包名以及包的入口文件等信息。
配置 TypeDoc
在 TypeScript 的配置文件 tsconfig.json 中，我们需要增加以下配置：
-- -------------------- ---- -------
-
------------------ -
-- --- --
-------------- -----
--------- ---------
---------- ----
-------- -
---------------- -----------
-
-
-这里的关键在于 declaration 和 outDir 两个配置项。我们需要将 declaration 设置为 true，以便 TypeDoc 正确读取 TypeScript 文件中的类型声明并生成 .d.ts 文件。而 outDir 表示生成的 .d.ts 文件的保存路径。上述设置中，我们将生成的文件保存到根目录下的 ./dist 目录。
配置 TypeDoc 插件
同时，我们需要在 tsconfig.json 中指定 TypeDoc 插件。我们增加 typedoc.json 配置文件，并在其中增加以下配置：
-- -------------------- ---- ------- - ------ --------- ------- ------- --------------------- ----- ----------------- ----- ------------------- ----- ------- --- --------- --------- ---------------------------- --------- ------------------- ------------------- -------- --------- -
这里的关键在于 plugin 配置项，我们需要将该配置项设置成 typedoc-plugin-markdown，以启用该插件。同时，我们还需要配置 out 表示生成的文档保存路径。后面的 assets 是指生成的 Markdown 文件需要引用的资源文件，可以根据情况进行修改。theme 表示使用的主题，我们可以将其设置为 default。
生成 API 文档
在完成 TypeScript 和 TypeDoc 的配置后，我们可以执行以下命令来生成 API 文档：
typedoc
如果一切配置正确，那么我们就可以看到在 ./docs 目录下生成了一份 HTML 格式的文档。
将 HTML 转换为 Markdown
有了 HTML 文档还不够，我们还需要将其转换为 Markdown 格式。针对不同的情况，我们推荐两种方法进行转换。
方法一：使用转换工具
可以使用工具将 HTML 文档转换为 Markdown。推荐使用 Turndown，这是一个轻量的 JavaScript 库，适合在前端项目中使用。以下是使用 Turndown 的示例代码：
-- -------------------- ---- ------- ------ --------------- ---- ----------- ------ -- ---- ----- ----- ------ - ------------------------------------ - --------- ------- --- ----- --------------- - --- ------------------ ----- -------- - --------------------------------- ----------------------------------- ----------
这里的关键在于 TurndownService() 和 turndown() 两个方法，分别表示创建 Turndown 实例和将 HTML 转换为 Markdown。
不过，如果你想更加自由地定制文档内容，还是可以选择另一种方法。
方法二：使用 typedoc-plugin-markdown 自带的渲染器
在 tsconfig.json 配置文件中，我们可以增加 typedoc-plugin-markdown 的配置项：
-- -------------------- ---- -------
-
------ ---------
------- -------
--------------------- -----
----------------- -----
------------------- -----
------- --- ---------
--------- ----------------------------
--------- ------------------- -------------------
-------- ----------
----------------- -
------------ -------------
-------- ------------------
--------- ------------------
--------------- ---- -----------
-------------- -------- ------
----------------- ----------- ------
------------- ------- ------
---------------- ---------- ------
---------------- ---------- ------
------------ ------ ------
------------ ------ ------
---------------- ---------- ------
-------------- ---------
-------------- -------------
----------- ---- ------
------------------ -------------
------------------ -------------
--------------- ---------
-
-其中，markdownPlugin 表示 typedoc-plugin-markdown 内置的 Markdown 渲染器的配置项，我们通过该配置项可以修改渲染器的输出格式。具体包括：
idPattern表示 MarkDown 文件所在的文件夹，我们可以通过$id参数来引用对应的文档；index表示渲染器输出的索引文件；readme表示渲染器输出的 README 文件；globalsTitle表示全局 API 的标题；moduleTitle表示模块 API 的标题；interfaceTitle表示接口的标题；classTitle表示类的标题；functionTitle表示函数的标题；variableTitle表示变量的标题；typeTitle表示类型的标题；enumTitle表示枚举类型的标题；templateTitle表示模板类型的标题；importTitle表示导入的标题；paramsTitle表示参数的标题；seeTitle表示另请参阅的标题；attributesTable表示属性的表格标题；parametersTable表示参数表格的标题；returnsTable表示返回值表格的标题。
示例代码
针对上述介绍，我们提供完整的示例代码，供读者参考：
-- -------------------- ---- -------
-
------------------ -
--------- -----------
--------- ------
---------------- -----
----------------- -----
-------------- -----
--------- ---------
---------- ----
-------- -
---------------- -----------
-
--
---------- -------------
---------- ---------------- ------- -----------
---------- --
--- -------------------- ---- -------
-
------ ---------
------- -------
--------------------- -----
----------------- -----
------------------- -----
------- --- ---------
--------- ----------------------------
--------- ------------------- -------------------
-------- ----------
----------------- -
------------ -------------
-------- ------------------
--------- ------------------
--------------- ---- -----------
-------------- -------- ------
----------------- ----------- ------
------------- ------- ------
---------------- ---------- ------
---------------- ---------- ------
------------ ------ ------
------------ ------ ------
---------------- ---------- ------
-------------- ---------
-------------- -------------
----------- ---- ------
------------------ -------------
------------------ -------------
--------------- ---------
-
--- -------------------- ---- ------- ------ --------------- ---- ----------- ------ -- ---- ----- ----- ------ - ------------------------------------ - --------- ------- --- ----- --------------- - --- ------------------ ----- -------- - --------------------------------- ----------------------------------- ----------
总结
以上就是使用 typedoc-plugin-markdown 的详细教程。在项目开发中，我们可以利用该插件帮助我们生成并管理 API 文档，从而提高开发效率和项目可维护性。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/57409