gitbook 插入图片_docsify 入坑指南与我放弃 Gitbook 的那些理由
Rum 的题解越来越多,原先选择 Gitbook 构建解题本的弊端逐渐显现出来,每次补充一道题解重新 build
项目时居然要花上 30 秒左右……
由于无法忍受 gitbook build
的速度和大量垃圾静态文件,我打算重新构建 Rum,因此有了与 docsify 的邂逅。
docsify 是什么?
官方的介绍是:
A magical documentation site generator.
与 Gitbook 和 VuePress 相同,docsify 是一个文档站点生成器。至于它究竟 magic 在何处,我将在后面说到。
快速开始
安装
首先全局安装 docsify-cli
:
npm i docsify-cli -g
初始化
假设我们要在 ./docs
子目录中编写文档,将该目录初始化:
docsify init ./docs
初始化后系统帮我们生成了一个 ./docs
目录,目录中包含以下文件:
index.html
:入口文件README.md
:将作为主页渲染.nojekyll
:阻止 Github Pages 忽略以下划线开头的文件
预览
使用以下命令启动本地服务器:
docsify serve docs
路由说明
页面路由和文件夹的对应关系如下:
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
导航与侧边栏配置
导航栏
简单导航栏
简单的导航栏可以在 index.html
文件中直接定义:
<body><nav><a href="#/">LeetCode 题解</a><a href="http://jalan.space" target="_blank">我的博客</a></nav><div id="app"></div>
</body>
复杂导航
复杂导航可以通过 Markdown 文件配置。
首先配置 loadNavbar
为 true
:
<script>window.$docsify = {loadNavbar: true}
</script>
<script src="//unpkg.com/docsify"></script>
在 ./docs
下创建一个 _navbar.md
文件,在该文件中使用 Markdown 格式书写导航:
* 导航1* [子导航](nav1/child/)
* [导航2](nav2/)
侧边栏
默认情况下,侧边栏会根据当前文章的标题生成目录。但也可以通过 Markdown 文档生成。
首先配置 loadSidebar
选项为 true
:
<script>window.$docsify = {loadSidebar: true}
</script>
<script src="//unpkg.com/docsify"></script>
然后在 ./docs
下创建 _sidebar.md
文件:
* [简介](/)
* 数据结构* [数组](data-structure/array/)* [字符串](data-structure/string/)* [链表](data-structure/linked_list/)* 树* [递归](data-structure/tree/recursion/)* [层次遍历(BFS)](data-structure/tree/bfs/)* [前中后序遍历(DFS)](data-structure/tree/dfs/)* [其他](data-structure/tree/other/)* [堆](data-structure/heap/)* [栈](data-structure/stack/)* [哈希表](data-structure/hash/)
* 算法思想* 排序* [堆排序](algorithm/sort/heap/)* [快速排序](algorithm/sort/quick/)* [冒泡排序](algorithm/sort/bubble/)* [其他](algorithm/sort/other/)* 搜索* [深度优先](algorithm/research/dfs/)* [广度优先](algorithm/research/bfs/)* [二分查找](algorithm/research/binary-search/)* [动态规划](algorithm/dynamic/)* [贪心](algorithm/greedy/)* [位运算](algorithm/bit/)* [数学题](algorithm/math/)* [其他](algorithm/other/)
* 周赛* [第 121 场周赛](weekly/121/)* [第 122 场周赛](weekly/122/)* [第 124 场周赛](weekly/124/)* [第 129 场周赛](weekly/129/)* [第 130 场周赛](weekly/130/)* [第 131 场周赛](weekly/131/)* [第 133 场周赛](weekly/133/)* [第 134 场周赛](weekly/134/)* [第 136 场周赛](weekly/136/)* [第 137 场周赛](weekly/137/)* [第 138 场周赛](weekly/138/)
插件
代码高亮
使用 Prism 作为代码高亮插件,可以在 index.html
中这样配置:
<script src="//unpkg.com/docsify"></script>
<script src="//unpkg.com/prismjs/components/prism-bash.js"></script>
<script src="//unpkg.com/prismjs/components/prism-php.js"></script>
注意这里引入的文件,如果你要高亮 Python 代码,那么就要引入:
<script src="//unpkg.com/prismjs/components/prism-python.js"></script>
对不同语言的高亮支持可见 Prism 仓库。
更多插件见 插件列表。
部署到 Github Pages
我的 Github Pages 读取的是 gh-pages
分支下的代码,因此我要把 ./docs
下的文件上传到 gh-pages
分支上,完整的代码则上传的到 master
分支。
为了方便更新,我在项目根目录下放置了一个用于推送代码的脚本 push.sh
:
message=$1# 复制 README.md
cp README.md docs/README.md# 更新 master
git add .
git commit -m "$message"
git push -f git@github.com:JalanJiang/leetcode-notebook.git master# 更新 gh-pages
cd docs/
git init
git add -A
git commit -m "$message"
git push -f git@github.com:JalanJiang/leetcode-notebook.git master:gh-pages
与 Gitbook 体验对比
初次搭建这一类文档站点使用的是 Gitbook, 之前写过一篇 搭建 GitBook 并托管到 git pages,目前我仓库里可见的文档站点几乎都是 Gitbook搭建的。然而很早开始 Gitbook 团队就专注于 Gitbook 的商业化项目,命令行工具已经被抛弃了……
两者最大的不同点是: docsify 是轻量级、无需编译的,而 Gitbook 每次 build
都需要生成一堆 HTML
静态文件,不仅 build
时间长,还污染了我的提交记录…… ♂️
而在插件方面,虽然 docsify 插件不如 Gitbook 的丰富,但麻雀虽小五脏俱全,该有的基本也都有,足够使用。
如果再建文档站点,我估计再也不会回去使用 Gitbook 了。
参考资料与扩展阅读
docsifydocsify.js.org
原创不易,如果你觉得文章写得不错,欢迎关注公众号「编程拯救世界」~
gitbook 插入图片_docsify 入坑指南与我放弃 Gitbook 的那些理由相关推荐
- overleaf 插入图片_LaTeX入坑小记
[参考视频:点这里] 目录 一.texlive2018环境安装 二.texstudio编辑器安装 三.基础快速入门 四.中文处理 五.字体设置 六.提纲和文档结构 七.特殊字符 八.插入图片 九.插入 ...
- Camunda BPM工作流引擎入坑指南(一)
Camunda BPM工作流引擎入坑指南 欢迎使用Camunda BPM工作流 入坑说明书 入坑准备工作 BPMN2.0基础 Camunda实战 Camunda BPM Activiti对比 功能快捷 ...
- python web-python web入坑指南
原标题:python web入坑指南 Invest regularly in your knowledge portfolio. Make learning a habit. 自学python web ...
- Rust 入坑指南:鳞次栉比 | CSDN 博文精选
作者 | Jackyzhe 责编 | 屠敏 出品 | CSDN(ID:CSDNnews) 很久没有挖Rust的坑啦,今天来挖一些排列整齐的坑.没错,就是要介绍一些集合类型的数据类型."鳞次栉 ...
- 开发工具篇第九讲:菜鸟入坑指南
摘要:本文是开发工具篇第九讲:菜鸟入坑指南.针对新人上手慢的问题,写了这篇入坑指南,方便自己回顾,总结.本文分为四个部分,分别为jenkins使用技巧:常用软件操作命令:开发手册:调试手册.主要材料来 ...
- Rust入坑指南:鳞次栉比
很久没有挖Rust的坑啦,今天来挖一些排列整齐的坑.没错,就是要介绍一些集合类型的数据类型."鳞次栉比"这个标题是不是显得很有文化? 在Rust入坑指南:常规套路一文中我们已经介绍 ...
- 百度OCR(文字识别)服务使用入坑指南
百度OCR使用入坑指南 一.背景:什么是OCR 二.在线调用百度api接口 1. 注册百度智能云账号,创建应用获取key 2. 调用api发送请求,获取文字识别结果 2.1 构造请求 2.2 识别结果 ...
- rust的矿坑_Rust入坑指南:鳞次栉比
很久没有挖Rust的坑啦,今天来挖一些排列整齐的坑.没错,就是要介绍一些集合类型的数据类型."鳞次栉比"这个标题是不是显得很有文化? 在Rust入坑指南:常规套路一文中我们已经介绍 ...
- 发布开源框架到CocoaPods入坑指南
个人原文博客地址: 发布开源框架到CocoaPods入坑指南 在开发过程中一定会用到一些第三方框架, 只要安装了CocoaPods, 然后通过pod install命令, 就可以集成框架到项目中了 可 ...
最新文章
- 全球大数据发展分析报告
- 笔记本建立wifi热点!(主要针对XP)【直播】
- [HDOJ3652]B-Number(数位dp)
- Mac~git学习和应用需要注意的几个点
- 顺序表应用1:多余元素删除之移位算法
- 工作总结-基于R的数据分析
- LBP(局部二值模式)特征提取原理
- json支持的最大长度_Swifter.Json 可能是 .Net 平台迄今为止性能最佳的 Json 序列化库【开源】...
- python从socket做个websocket的聊天室server
- C学习杂记(三)笔试题:字符串大小写字母切换
- droidbox官网
- 【2016年第1期】山东省农业大数据发展刍议
- 怎么写显示商品图片_虾皮商店封面图片 虾皮商店介绍怎么写吸引人
- linux Wi-Fi信号放大,wifi信号增强器
- ssis 角本组件更新数据_使用SSIS脚本组件作为数据源
- Flutter 常用的按钮组件
- wireshark抓包QQ查IP
- 第五章 机械臂的组装及控制
- matlab整数规划分支计算,分支定界法求线性整数规划
- 描述一下普适计算时代中的计算机,浅析普适计算及其应用.doc