绍兴建设用地使用权网站,静态网页扩展名,淘宝客15套单页网站程序模板打包,wordpress百度搜索一个不到 10MB 的小工具#xff0c;来提供本地、快速的文档访问#xff0c;来改善开发过程中#xff0c;阅读在线文档体验糟糕的问题。
以及#xff0c;介绍如何快速制作一个利于分发使用的#xff0c;离线文档工具包。
写在前面
即使现在 AI 辅助编码和 Chat Bot 类的…一个不到 10MB 的小工具来提供本地、快速的文档访问来改善开发过程中阅读在线文档体验糟糕的问题。
以及介绍如何快速制作一个利于分发使用的离线文档工具包。
写在前面
即使现在 AI 辅助编码和 Chat Bot 类的产品已经非常多写代码的体验已经变的非常好但是日常 Coding 过程中我们难免还需要翻阅开源产品的文档。
因为各种原因包括部署在 GitHub Pages 上的文档的访问体验都一言难尽。在浏览文档的时候浏览器时不时转圈圈非常影响连续的思路以及非常的浪费时间。
尤其是在《你的网站或许不需要前端构建二》这篇文章中我提到了多款非常不错的前端框架和工具它们的文档都托管在 GitHub 上。
而且单纯是将这些文档下载到本地也并不完全能够解决访问慢的问题因为文档中可能还引用了一些外部的 API 接口或者互联网小组件这些小组件加载好之前页面可能都是“白页”。
所以结合今年早先时候的文章《完善 Golang Gin 框架的静态中间件Gin-Static》折腾了一个小工具来提供本地、快速的文档访问来改善开发过程中阅读在线文档体验糟糕的问题。
项目开源在 soulteary/docker-quick-docs欢迎一键三连或有需要的代码自取。
将在线文档转换为本地文档
我们以 baidu/san 部署在 GitHub Pages 上的在线文档为例来将它变为可以快速访问的本地文档。
获取文档数据
类似这个项目部署在 GitHub Pages 上的内容通常都会在项目的 gh-pages 分支上所以我们有两种方式来获取文档内容第一种是在页面中先切换项目分支到 gh-pages然后点击下载代码的按钮得到源码压缩包。 不过这种方式我们更新代码内容比较麻烦所以我更推荐第二种方法使用 git clone 携带参数来下载指定目录的代码并尽量少的进行 clone
git clone http://github.com/baidu/san --depth 1 --branchgh-pages代码执行后我们就能相对快速的从仓库中得到可更新的文档数据了
# git clone http://github.com/baidu/san --depth 1 --branchgh-pages
Cloning into san...
warning: redirecting to https://github.com/baidu/san/
remote: Enumerating objects: 405, done.
remote: Counting objects: 100% (405/405), done.
remote: Compressing objects: 100% (197/197), done.
remote: Total 405 (delta 154), reused 303 (delta 65), pack-reused 0
Receiving objects: 100% (405/405), 2.17 MiB | 5.18 MiB/s, done.
Resolving deltas: 100% (154/154), done.如果后续想更新代码只需要进入目录执行 git pull
# cd san
# git pull
Already up to date.启动 Quick Docs
使用 Quick Docs 有两种方法一种是从 GitHub 发布页面 下载适合你系统的二进制文件然后直接执行它。
./quick-docs默认情况下它将在目录中自动创建 docs 目录将我们准备好的文档都保存在这个目录中就可以来做本地体验了默认的端口是 8080。
如果你想调整端口可以设置命令中的环境变量 PORT比如想要在 9000 端口运行我们可以这样做
PORT9000 ./quick-docs当然如果你是 Docker 爱好者我们有更“绿色环保”的方案
# 下载工具
docker pull soulteary/docker-quick-docs:v0.1.2
# 使用工具启动文档
docker run --rm -it -v pwd/docs:/app/docs -p 8080:8080 soulteary/docker-quick-docs:v0.1.2当程序执行完毕我们将能够看到类似下面的输出结果
2024/01/04 11:39:54 Quick Docs v0.1.2这个时候我们访问 http://localhost:8080 就能够看到有哪些目录可以被浏览了。 因为我们只存放了 san 一个项目的文档所以在打开浏览器之后我们暂时就只有这一个目录可访问。如果你想访问更多的文档只需要将不同的文档都放到 docs 目录然后启动程序即可。
点击目录我们就能够看到 san 的本地部署文档啦 不同与 GitHub 慢吞吞的本地部署的文档访问速度提升非常明显如果你经常访问某些开源软件的文档这个方案一定可以为你节约大量的时间。
一般情况下做到这一步文档的本地化访问就已经搞定了。不过相信追求极致的你一定希望本地的页面能够打开的更快甚至完全离线可访问那么我们继续来折腾。
高级功能文档内容重写
我们继续以 san 的文档为例我们打开网络调试工具再次刷新页面能够看到有两个很明显的加载比较慢的请求。 想要解决这个问题我们可以使用工具支持的“内容重写功能”。
简单重写
以上面的内容为例上面页面中比较慢的请求地址分别是
https://cdn.jsdelivr.net/docsearch.js/2/docsearch.min.css
https://ghbtns.com/github-btn.html?userbaidureposantypestarcounttruesizelarge比如我们可以将上面的请求改写为“空”来避免慢请求
[{from: https://cdn.jsdelivr.net/docsearch.js/2/docsearch.min.css,to: },{from: https://ghbtns.com/github-btn.html,to: about:blank}
]我们将上面的内容保存为 config.json如果你是使用可执行文件运行程序那么重启程序程序就会自动加载并应用配置文件了。
如果你是 Docker 用户那么我们需要调整命令将这个配置文件映射到容器内
docker run --rm -it -v pwd/docs2:/app/docs -v pwd/config.json:/app/config.json -p 8080:8080 soulteary/docker-quick-docs:v0.1.2当程序执行完毕我们将看到类似下面的输出
2024/01/04 12:06:57 Quick Docs v0.1.2
2024/01/04 12:06:57 未设置环境变量 PORT使用默认端口8080
2024/01/04 12:06:57 解析配置文件成功规则数量: 2此时再打开页面刷新网页我们就能看到所有的请求都来自本地以及感受到页面请求速度更快啦。 只要你想你可以放任意数量的文档在 docs 目录中来改善你的开发文档阅读体验。
更高性能的重写
不过倘若我们有很多文档目录也有非常多的重写规则那么一定会造成不必要的性能损失即使程序本身足够简单现代硬件的性能也足够高。
但如果你的 Quick Docs 是运行在使用电池支持的笔记本上或者单核心的小主机上能省则省嘛。
我们只需要在上面的重写规则下面添加 dir 字段来限制重写规则的生效范围即可如果你想更进一步的进行限制还可以设置重写内容的类型 type
[{from: https://ecomfe.github.io/san/,to: /san/,type: html,dir: /san/},{from: https://github.com/baidu/san-router,to: /san-router/},{from: https://ecomfe.github.io/santd/,to: /santd/}
]默认情况下如果我们不设置 dir 或者 type那么程序将对所有目录下的 html 文件生效。
目前支持处理的文件类型包括 html、js、css、json对于离线的文档站来说应该是足够使用了吧如果你觉得不够用欢迎在项目 issue 中提出你的看法。
好了如果你有很多文档需要本地托管看到这里也足够应对啦。
构建利于分发的单程序文档
文档的开头我提到了如何制作一个利于分发使用的离线文档工具包。这里主要是复用早些时候发的文章《完善 Golang Gin 框架的静态中间件Gin-Static》中的中间件的能力。
想要制作单文件的离线工具包我们需要先下载项目代码
git clone https://github.com/soulteary/docker-quick-docs.git然后和上文一样将我们想固化在程序中的文档放在 docs 目录中。
执行程序构建命令
go build -o quick-docs程序执行完毕我们在当前目录就能够得到“内置”了文档的程序了它可以脱离之前的 docs 目录运行。
我们的离线文档程序也就折腾好了运行的时候需要携带一个参数 EMBEDon 来激活 Embeded 功能
EMBEDon ./quick-docs程序的使用和上文中提到的没有任何差别。
最后
好了写到这里Quick Docs 的所有用法就都介绍完毕啦。
我们下篇文章再见。
–EOF 本文使用「署名 4.0 国际 (CC BY 4.0)」许可协议欢迎转载、或重新修改使用但需要注明来源。 署名 4.0 国际 (CC BY 4.0)
本文作者: 苏洋
创建时间: 2024年01月04日 统计字数: 4924字 阅读时间: 10分钟阅读 本文链接: https://soulteary.com/2024/01/04/improving-the-github-pages-reading-experience-quick-docs.html
