首页 » 脚本文章 » 一个优秀的程序员专属文档生成工具(开源)——docsify(文档开源工具配置程序员)

一个优秀的程序员专属文档生成工具(开源)——docsify(文档开源工具配置程序员)

admin 2024-07-23 19:41:27 脚本文章 0

扫一扫用手机浏览

文章目录 [+]

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

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

npm i docsify-cli -g

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

yarn global add docsify-cli

然后我们就可以使用了,如下:

一个优秀的程序员专属文档生成工具(开源)——docsify(文档开源工具配置程序员) 一个优秀的程序员专属文档生成工具(开源)——docsify(文档开源工具配置程序员) 脚本文章
(图片来自网络侵删)

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

然后执行以下命令

一个优秀的程序员专属文档生成工具(开源)——docsify(文档开源工具配置程序员) 一个优秀的程序员专属文档生成工具(开源)——docsify(文档开源工具配置程序员) 脚本文章
(图片来自网络侵删)

docsify init ./docs

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

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

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

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

接下来是预览效果:

cd docsdocsify serve

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

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

<!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.comdocs/guide.md => http://domain.com/guidedocs/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。

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

<!-- _navbar.md --> [En](/) [中文](/zh-cn/)嵌套

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

<!-- _navbar.md --> 入门 [快速开始](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)

定制化

如果上面都还不满足,那么它还可以定制化:

配置项:提供几十种配置项(使用时可以查看文档)主题支持

如果还不满足,那么docs还有人为之开发了主题系统

https://github.com/jhildenbiddle/docsify-themeable

插件列表

全文搜索 - Search、谷歌统计 - Google Analytics、emoji、外链脚本 - External Script、图片缩放 - Zoom image、在 Github 上编辑、代码即时预览和 jsfiddle 集成、复制到剪贴板

、Disqus、Gitalk、Pagination、字数统计、Code Fund、Tabs自定义插件

自定义插件

docsify 提供了一套插件机制,其中提供的钩子(hook)支持处理异步逻辑,可以很方便地扩展功能。

Markdown 配置

内置的 Markdown 解析器是 marked,可以修改它的配置。
同时可以直接配置 renderer。

代码高亮

docsify内置的代码高亮工具是 Prism。
Prism 默认支持的语言如下:

Markup - markup, html, xml, svg, mathml, ssml, atom, rssCSS - cssC-like - clikeJavaScript - javascript, js更多功能和用法

Docs确实很强大,以下用法和功能,在官方文档中也详细地介绍了,包括之前说的部署到Github Pages

部署文档助手兼容 VueCDN离线模式(PWA)服务端渲染 (SSR)文件嵌入

文档地址:

https://docsify.js.org/#/zh-cn/embed-files

本身也是开源项目:

https://github.com/docsifyjs/docsify

推荐对照文档进行详细的使用

标签:

相关文章