前言
随着前端开发越来越复杂，我们需要更好的代码组织和文档管理方式。ESDoc 是一个常用的 JavaScript 文档生成工具，它可以从代码中自动生成可读性高、易于理解的 API 文档。
ESDoc 默认主题简单实用，但是没有定制化的功能。本文将介绍如何使用 esdoc-brand-plugin 包制作定制化 ESDoc 主题，并探讨其深层次原理，以及如何使用这个包进行自定义主题制作。
安装与配置
安装 esdoc-brand-plugin 包：
$ npm install --save-dev esdoc-brand-plugin
在项目的 esdoc.json 配置文件中添加以下内容：
-- -------------------- ---- -------
-
---------- -
-------- --------------------- --------- -
-------- --- ------ ------
------- --------------------
------ ---------------------
--
-
-其中：
title: 文档网站的标题。logo: 网站顶部的 logo 图片路径。css: 自定义 CSS 文件路径。
深入研究
esdoc-brand-plugin 的实现原理是基于 ESDoc 插件机制，通过 Hook 钩子函数来拦截并改变默认主题模板的渲染结果。具体步骤如下：
- 在
esdoc.json中添加插件配置项。 - 在插件初始化阶段，通过 Hook 钩子函数获取默认主题模板路径和渲染参数。
- 通过修改渲染参数中的数据，实现对默认主题模板的改变。
- 生成自定义主题文档。
esdoc-brand-plugin 内部实现了以下钩子函数：
onHandleConfig: 插件初始化时触发，用于读取配置信息。onComplete: 文档生成完成后触发，用于拷贝自定义 CSS 文件到生成目录。onCompleteHTML: 生成 HTML 文件时触发，用于替换模板中的数据。
示例代码
假设我们有一个项目结构如下：
. ├── esdoc.json ├── index.js └── README.md
其中 index.js 文件内容如下：
-- -------------------- ---- ------- --- - -- ------ ------- - - ------- --------- -- --- - --- --- ------- --------- - - ------ -------- - - --- ----- ------ -- ---- - ------ -------- - - --- ------ ------ -- ---- - -------- -------- --- --- -- --- --- ----- -------- -- -------- ------ -- - ------ - - -- - --- - -------- --- ------ ---- -------- - - ------ -------- - - --- ------ -- -------- ----- - ------ -------- - - --- ------ -- --------- - -------- -------- --- ------ -- --- ------------ -- -------- ----------- -- - ------ - - -- -
我们要制作一个自定义主题，包含以下改变：
- 修改网站标题为 "My Custom Docs"
- 在网站顶部添加一个 Logo 图片
- 替换默认 CSS 样式
首先安装 esdoc-brand-plugin 包：
$ npm install --save-dev esdoc-brand-plugin
修改 esdoc.json 配置文件如下：
-- -------------------- ---- -------
-
--------- -----
-------------- ---------
---------- -
-------- --------------------- --------- -
-------- --- ------ ------
------- --------------------
------ ---------------------
--
-
-在项目根目录下新建 logo.png 和 custom.css 文件，分别存放 Logo 图片和自定义 CSS 样式。
运行 esdoc 命令生成文档：
$ npx esdoc
打开生成的文档目
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/47265