专栏首页编程拯救世界工具安利 | docsify 入坑指南与我放弃 Gitbook 的那些理由

工具安利 | docsify 入坑指南与我放弃 Gitbook 的那些理由

  • docsify 是什么?
  • 快速开始
    • 安装
    • 初始化
    • 预览
  • 路由说明
  • 导航与侧边栏配置
    • 导航栏
    • 侧边栏
  • 插件
    • 代码高亮
  • 部署到 Github Pages
  • 与 Gitbook 体验对比

leetcode-notebook[1] 的题解越来越多,原先选择 Gitbook[2] 构建解题本的弊端逐渐显现出来,每次补充一道题解重新 build 项目时居然要花上 30 秒左右……

由于无法忍受 gitbook build 的速度和大量垃圾静态文件,我打算重新构建项目,因此有了与 docsify[3] 的邂逅。

docsify 是什么?

官方的介绍是:

A magical documentation site generator.

与 Gitbook 和 VuePress[4] 相同,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 文件配置。

首先配置 loadNavbartrue

<script>
  window.$docsify = {
    loadNavbar: true
  }
</script>
<script src="//unpkg.com/docsify"></script>

./docs 下创建一个 _navbar.md 文件,在该文件中使用 Markdown 格式书写导航:

- 导航 1
  - [子导航](nav1/child/ "子导航")
- [导航 2](nav2/ "导航2")

侧边栏

默认情况下,侧边栏会根据当前文章的标题生成目录。但也可以通过 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/ "层次遍历(BFS)")
    - [前中后序遍历(DFS)](data-structure/tree/dfs/ "前中后序遍历(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/ "第 121 场周赛")
  - [第 122 场周赛](weekly/122/ "第 122 场周赛")

插件

代码高亮

使用 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 仓库[5]


更多插件见 插件列表[6]

部署到 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[7],目前我仓库里可见的文档站点几乎都是 Gitbook 搭建的。然而很早开始 Gitbook 团队就专注于 Gitbook 的商业化项目,命令行工具已经被抛弃了……

对比项

docsify

Gitbook

是否需要编译

插件

较少

阅读体验

极好

灵活性

较好

较差

其中最大的不同点还是 docsify 是轻量级、无需编译的,而 Gitbook 每次 build 都需要生成一堆 HTML 静态文件,不仅 build 时间长,还污染了我的提交记录……‍?‍♂️

而在插件方面,虽然 docsify 插件不如 Gitbook 的丰富,但麻雀虽小五脏俱全,该有的基本也都有,足够使用。

如果再建文档站点,我估计再也不会回去使用 Gitbook 了。

参考资料

[1]

leetcode-notebook: https://github.com/JalanJiang/leetcode-notebook

[2]

Gitbook: https://www.gitbook.com/

[3]

docsify: https://docsify.js.org/#/

[4]

VuePress: https://github.com/vuejs/vuepress

[5]

Prism 仓库: https://github.com/PrismJS/prism

[6]

插件列表: https://docsify.js.org/#/plugins

[7]

搭建 GitBook 并托管到 git pages: http://jalan.space/2018/04/22/2018/2018-04-22-gitbook-and-git-pages/

本文分享自微信公众号 - 编程拯救世界(CodeWarrior_),作者:江子抑

原文出处及转载信息见文内详细说明,如有侵权,请联系 yunjia_community@tencent.com 删除。

原始发表时间:2019-11-30

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

我来说两句

0 条评论
登录 后参与评论

相关文章

  • 开源世界大冒险 | 第 4 期:Git 基础

    在上一章中我们说到GitHub 并不等同于 Git,在这一篇文章中我们就来了解 Git 和它的基本使用。

    江不知
  • 开源世界大冒险 | 第 2 期:Git 基础

    在第二期《开源世界大冒险 | 第 2 期:聊聊版本控制》中,我们对版本控制进行了讲解。Git 就是目前世界上最先进的分布式版本控制系统,它支持离线工作且高度自由...

    江不知
  • 浅谈 Python 中的比较运算符

    自己在写代码的时候很少去关注变量的比较要如何实现,基本都是直接使用 == 。今天就借此机会聊聊 Python 中的比较运算符。

    江不知
  • 腾讯Android开发面试记录

    Q1:你简单介绍一下自己吧。 A:我大三开始接触Android开发。之后有三段实习经历,大四有半年在A公司的APP进行开发,主要负责2个任务,分别是xxx和y...

    Android技术干货分享
  • 云HR和财务软件成为资本市场下一个热点

    企业级市场近两年备受投资热捧,移动CRM厂商成为最大受益者,D轮1亿美金已经让移动CRM的资本趋向集中,这时很多人都在问下一轮企业级市场的投资热点在哪儿?据移动...

    人称T客
  • HR SaaS or社群电商,谁才是打开HR市场的真正钥匙?

    一直以来,人力资源服务都是个典型的“外冷内热”行业,尽管几乎所有成人都会接触到,但行业里的血雨腥风只有从业者自己感受得到。有关专家表示,预计“十三五”末,全国人...

    曾响铃
  • 阿里offer,终于等到了offer call,内附面经

    牛客网
  • 当HR遇上大数据,我们看看腾讯是如何做的?

    ? 搜索一下“HR+大数据”,可以轻松得到几百万条记录,可见大数据在HR领域并不是一个陌生的话题,遗憾的是,热度有余而深度不足。北大光华的穆胜博士在其写的《大...

    灯塔大数据
  • HR说:35岁,程序员不如狗,20岁还能抖一抖

    上周有一篇文章,36氪专访HR的,是我非常想要拿出来讲的。但是工作进入了繁忙期,所以我也就拖到了今天。文章是这样的:比年轻人贵,没年轻人身体好,为什么要你?| ...

    用户1564362
  • 程序员面试的坑?你防不胜防

    我们要根据自身的不同情况来有针对性地回答问题,我们要让HR觉得这个理由合情合理,而且还不会让HR对我们产生顾虑,HR能够很放心的把我们招进公司为公司服务。

    本人秃顶程序员

扫码关注云+社区

领取腾讯云代金券