idea快速生成接口文档方法（一个优秀的程序员专属文档生成工具）

介绍

docsify是一个神奇的文档网站生成器。docsify不同于很多静态博客那样的方式生成html的静态网页文件，而是在运行时进行转换。只需要创建一个index.html文件，就可以编写文档并部署到Github Pages。

idea快速生成接口文档方法（一个优秀的程序员专属文档生成工具）(1)

支持的特性

无需构建，写完文档直接发布
容易使用并且轻量 (压缩后 ~21kB)
智能的全文搜索
提供多套主题
丰富的 API
支持 Emoji
兼容 IE11
支持服务端渲染 SSR

开始安装使用

这里在官方的文档中推荐安装一个全局的docsify-cli脚手架工具，这样就能很方便地每次使用它了，我们可以使用npm来进行安装

npm i docsify-cli -g

笔者比较习惯使用yarn，如果你也一样，可以和我一样使用以下命令安装

yarn global add docsify-cli

然后我们就可以使用了，如下：

我们先使用命令行工具到你项目的文件夹中，比如我这里是使用mydoc：

然后执行以下命令

docsify init ./docs

PS：如果你使用yarn，然后执行命令失败，那么你需要将你的yarn的bin目录添加到你的环境变量中，windows下直接就在Path下面加上即可，可以使用 yarn global bin命令查看你的yarn的bin文件夹目录

idea快速生成接口文档方法（一个优秀的程序员专属文档生成工具）(2)

初始化成功后，可以看到 ./docs 目录下创建的几个文件

index.html 入口文件
README.md 会作为主页内容渲染
.nojekyll 用于阻止 GitHub Pages 忽略掉下划线开头的文件

直接编辑 docs/README.md 就能更新文档内容，当然也可以添加更多页面。

接下来是预览效果：

cd docs docsify serve

浏览器打开页面localhost:3000 即可查看效果，如下：

idea快速生成接口文档方法（一个优秀的程序员专属文档生成工具）(3)

当然，如果你不想使用提供的脚手架工具，你也可以使用官方文档中提到的手动创建，如下：

<!DOCTYPE html> <html> <head> <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"> <meta name="viewport" content="width=device-width,initial-scale=1"> <meta charset="UTF-8"> <link rel="stylesheet" href="//CDN.jsdelivr.net/npm/docsify/themes/vue.css"> </head> <body> <div id="app"></div> <script> window.$docsify = { //... } </script> <script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script> </body> </html>

将readme也加上当前目录下即可，然后需要启动一个静态服务器，这里笔者推荐使用liveServer，很好用的一个本地调试http静态服务器，下面你就可以自定义你的文档了

多页面文档

多页文档在docsify中也很容易实现，以下来自于文档中的介绍，大家可以自行尝试：

假设你的目录结构如下：

. └── docs ├── README.md ├── guide.md └── zh-cn ├── README.md └── guide.md

那么对应的访问页面将是

docs/README.md => http://domain.com docs/guide.md => http://domain.com/guide docs/zh-cn/README.md => http://domain.com/zh-cn/ docs/zh-cn/guide.md => http://domain.com/zh-cn/guide

这一块文档中有非常详细的介绍，快速开始——多页文档、定制侧边栏、嵌套的侧边栏、用侧边栏中选定的条目名称作为页面标题、显示目录、忽略副标题等等

自定义导航栏

同时你还可以自定义导航栏：

<nav> <a href="#/">EN</a> <a href="#/zh-cn/">中文</a> </nav> <div id="app"></div>

那我们可以通过 Markdown 文件来配置导航。首先配置 loadNavbar，默认加载的文件为 _navbar.md。具体配置规则见配置项#loadNavbar。

 <script> window.$docsify = { loadNavbar: true } </script> <script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>

 * [En](/) * [中文](/zh-cn/)

嵌套

如果导航内容过多，可以写成嵌套的列表，会被渲染成下拉列表的形式。

 * 入门 * [快速开始](zh-cn/quickstart.md) * [多页文档](zh-cn/more-pages.md) * [定制导航栏](zh-cn/custom-navbar.md) * [封面](zh-cn/cover.md) * 配置 * [配置项](zh-cn/configuration.md) * [主题](zh-cn/themes.md) * [使用插件](zh-cn/plugins.md) * [Markdown 配置](zh-cn/markdown.md) * [代码高亮](zh-cn/language-highlight.md)

idea快速生成接口文档方法（一个优秀的程序员专属文档生成工具）(4)