目录

docsify快速入门

docsify

根据官方说法,docsify是一个神奇的文档网站生成工具,也可以把它当做一个简易版的静态站点诸如Hexo、Hugo等。当然,它是专门针对文档的,忽然想到了程序员深恶痛绝的就是写API文档……

docsify特性很多,最吸引我的是全文搜索、主题简洁好看、无需构建的纯静态站点。这意味着可以很简单地把写完的文档直接扔到Pages服务上,比如GitHub Pages、Coding Pages等等。

快速安装

首先需要先安装npm,这里简单说下。安装npm之前需要先安装node.js,而博主是Windows系统,可以通过nvm-windows来安装node.js,具体可以参考这篇文章

然后用npm来全局安装docsify:

1
npm i docsify-cli -g

简易搭建

初始化

创建一个文档站点目录,比如note目录,然后在该目录下执行命令:

1
docsify init ./docs

然后docsify会在该目录下新建一个docs目录,里面有3个初始文件:

  • .nojekyll:告诉GitHub Pages服务该站点不使用Jekyll作为构建工具
  • index.html:入口文件
  • README.md:作为首页渲染

请尽量使用docs目录来初始化docsify,原因是后面要用该目录部署到GitHub Pages。

本地预览与实时更新

使用如下命令可以本地预览站点:

1
docsify serve docs

然后就可以通过http://localhost:3000/来访问你的文档站点。

docsify支持实时更新,可以在启动本地服务时自动重新加载刚刚更新的文件。

常用配置

站点标题、图标

站点标题需要修改index.html里的title标签:

1
<title>Java-Note</title>

站点图标要在index.html添加如下代码:

1
<link rel="icon" href="//cdn.jsdelivr.net/gh/lewky/lewky.github.io@master/images/avatar.jpg">

主题选择

docsify提供了多款主题,通过修改index.html里的css地址即可更换主题:

1
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">

还有以下的主题可以挑选,有遗漏的可以帮忙补充下:

1
2
3
4
5
6
7
8
9
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/buble.css">
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/dark.css">
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/pure.css">
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/dolphin.css">

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-defaults.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple-dark.css">

Github Corner

index.html里有个脚本代码如下:

1
2
3
4
5
6
  <script>
    window.$docsify = {
      name: '',
      repo: ''
    }
  </script>

name会作为标题显示在站点的侧边栏,repo会作为Github Corner显示在站点的右上角,点击可跳转到对应的地址。样例如下:

1
2
3
4
5
6
  <script>
    window.$docsify = {
      name: 'Java-Note',
      repo: 'https://github.com/lewky'
    }
  </script>

coverpage封面

该参数可以给站点添加一个封面,如下:

1
2
3
4
5
6
7
  <script>
    window.$docsify = {
      name: 'Java-Note',
      repo: 'https://github.com/lewky',
      coverpage: true
    }
  </script>

封面由_coverpage.md来渲染,默认无该文件需自行创建,内容如下:

1
2
3
4
5
6
7
8
9
![logo](https://docsify.js.org/_media/icon.svg)

# Java笔记

> 个人向的Java学习笔记

* 贵在坚持

[开始阅读](/README)

loadNavbar导航栏

该参数用于添加导航栏,如下:

1
2
3
4
5
6
7
  <script>
    window.$docsify = {
      name: 'Java-Note',
      repo: 'https://github.com/lewky',
      loadNavbar: true
    }
  </script>

同样需要新建文件_navbar.md,内容如下:

1
2
3
* [Home](/)
* Links
    * [CS-Notes](http://cyc2018.gitee.io/cs-notes/#/README)

loadSidebar侧边栏

该参数用于添加侧边栏,如下:

1
2
3
4
5
6
7
  <script>
    window.$docsify = {
      name: 'Java-Note',
      repo: 'https://github.com/lewky',
      loadSidebar: true
    }
  </script>

同样需要新建文件_sidebar.md,内容如下:

1
2
3
* [简介](/)
* 数据结构
  * [数组](data-structure/array/)

个人不建议用这个参数,docsify默认会帮你生成侧边栏,并且有目录效果,可以点击跳转。

全文搜索插件

docsify提供了一些插件,包括全文搜索等,可以通过该地址查询有哪些插件:https://cdn.jsdelivr.net/npm/docsify@4.12.0/lib/plugins/

对于全文搜索插件,需要在index.html里添加search属性以及JavaScript,官方提供的搜索插件好像有点问题,这里用的是其他的搜索插件。如下:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
  <script>
    window.$docsify = {
      name: 'Java-Note',
      repo: 'https://github.com/lewky',
	  search: {
		maxAge: 86400000, // Expiration time, the default one day
		paths: 'auto',
		placeholder: '🔍 Type to search ',
		noData: '😞 No Results! ',
		depth: 6
	  }
    }
  </script>
  <script src="//cdn.bootcss.com/docsify/4.5.9/plugins/search.min.js"></script>

目前似乎高于4.5.9版本的搜索插件有bug,只能搜索到首页的数据;建议使用该版本的搜索插件。

此外,使用了无序列表或者有序列表的数据是无法生成对应索引的,也就是说搜索插件无法搜索到列表里的数据。建议尽量别使用列表语法,可以改用特殊符号、罗马数字ⅠⅡⅢⅣⅤⅥⅦⅧⅨ 和换行符<br>来代替列表语法。

回到顶部插件

index.html引入脚本和参数配置:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
  <script>
    window.$docsify = {
      name: 'Java-Note',
      repo: 'https://github.com/lewky',
	  scrollToTop: {
        auto: true,
        text: 'Top',
        right: 15,
        bottom: 15,
        offset: 300
      }
    }
  </script>
  <script src="//unpkg.com/docsify-scroll-to-top/dist/docsify-scroll-to-top.min.js"></script>

参数配置有默认值,不配也可以,一共就这几个属性,可以自己随意定制。

代码高亮插件

index.html引入脚本,可以根据需要引入对应的语言高亮脚本:

1
2
3
4
<script src="//cdn.jsdelivr.net/npm/prismjs@1.22.0/components/prism-java.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/prismjs@1.22.0/components/prism-bash.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/prismjs@1.22.0/components/prism-c.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/prismjs@1.22.0/components/prism-sql.min.js"></script>

复制代码块插件

index.html引入脚本和参数配置:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
<script>
	window.$docsify = {
	  // docsify-copy-code (defaults)
	  copyCode: {
	    buttonText : 'Copy to clipboard',
	    errorText  : 'Error',
	    successText: 'Copied'
	  }
	}
</script>

<script src="//unpkg.com/docsify-copy-code@2.1.1/dist/docsify-copy-code.min.js"></script>

参数配置有默认值,可以不配置直接引入脚本即可使用。

图片缩放插件

index.html引入脚本即可:

1
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/zoom-image.min.js"></script>

添加fontawesome

可以通过引入fontawesome来使用各种免费的矢量图标来丰富页面内容:

1
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@fortawesome/fontawesome-free@5.13.0/css/all.min.css">

用法很简单,就是使用<i>标签来引入,而markdown兼容html代码,如下:

1
<i class="fas fa-fw fa-home"></i>

还有其他的动态图用法等,网上教程很多,这里就不赘述了。

PlantUML插件

index.html引入脚本即可:

1
<script src="//unpkg.com/docsify-plantuml/dist/docsify-plantuml.min.js"></script>

默认主题是default,也可以配置成classic

1
2
3
4
5
6
7
<script>
window.$docsify = {
  plantuml: {
    skin: 'classic',
  }
}
</script>

远程部署到Pages服务

GitHub Pages支持从三个地方读取文件:

  • docs目录
  • main分支(以前是叫master分支)
  • gh-pages分支

master分支一般用于个人站点,gh-pages分支需要另外创建一个新的分支(默认GitHub仓库创建的是master分支),对于文档站点,建议直接使用docs目录来部署,这也是前文为什么建议用docs目录进行初始化的原因。

将文档站点推送到GitHub仓库后,在Settings里选择使用main branch/docs进行部署即可。

参考链接

警告
本文最后更新于 April 14, 2023,文中内容可能已过时,请谨慎使用。