docsify - 生成文档网站简单使用教程

时间  2019-11-06
标签 docsify 生成 文档 网站 简单 使用 教程 栏目 网站开发 繁體版
原文   原文链接

1. docsify介绍

docsify 是一个动态生成文档网站的工具。不一样于 GitBook、Hexo 的地方是它不会生成将 .md 转成 .html 文件，全部转换工做都是在运行时进行。javascript

这将很是实用，若是只是须要快速的搭建一个小型的文档网站，或者不想由于生成的一堆 .html 文件“污染” commit 记录，只须要建立一个 index.html 就能够开始写文档并且直接部署在 GitHub Pages。css

2. 引入docsify方式

2.1 手动建立index.html并引入docsify文件

docsify使用方式很简单，只须要在项目中建立一个index.html文件，内容可以以下：html

<!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="//unpkg.com/docsify/themes/vue.css">
</head>
<body>
  <div id="app"></div>
  <script>
    window.$docsify = {
      //...
    }
  </script>
  <script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
</body>
</html>

而后在项目中建立一个README.md文件：vue

## 我是首页

这是个人首页介绍

若是你的系统安装了Python 的话，可使用Python来启动一个服务：java

python -m SimpleHTTPServer 3000

Serving HTTP on 0.0.0.0 port 3000 ...
127.0.0.1 - - [03/Jan/2019 13:45:27] "GET / HTTP/1.1" 200 -

clipboard.png
而后在浏览器中输入http://localhost:3000/查看浏览效果。node

若是没有Python，仍是可使用http-server启动服务，
可在终端输入npm install http-server -g来安装http-server。python

http-server 

Starting up http-server, serving ./
Available on:
  http://127.0.0.1:8080
  http://172.24.70.142:8080
Hit CTRL-C to stop the server

clipboard.png
而后在浏览器中输入http://127.0.0.1:8080查看浏览效果。react

clipboard.png

注意：
1.在此模式下编辑文件保存后，须要手动刷新浏览器才能看见修改的效果，下面介绍的docsify-cli可实现自动查看效果。
2.强烈建议把index.html文件中的docsify.min.js和vue.css文件复制到本地项目，而后使用以下方式引入：git

<link rel="stylesheet" href="./vue.css">
<script src="./docsify.min.js"></script>

这样作的好处是不在依赖网络环境了。github

2.2 使用docsify-cli来开发

docsify-cli 工具，能够方便建立及本地预览文档网站。

2.2.1 安装

docsify须要本地先安装node, 若是没有安装node，可在node官网选择对应操做系统下载安装：https://nodejs.org/zh-cn/

终端输入npm i docsify-cli -g进行全局安装：

npm i docsify-cli -g

/usr/local/bin/docsify -> /usr/local/lib/node_modules/docsify-cli/bin/docsify
> fsevents@1.2.4 install /usr/local/lib/node_modules/docsify-cli/node_modules/fsevents
> node install
[fsevents] Success: "/usr/local/lib/node_modules/docsify-cli/node_modules/fsevents/lib/binding/Release/node-v57-darwin-x64/fse.node" already installed
Pass --update-binary to reinstall or --build-from-source to recompile
> docsify@4.8.6 postinstall /usr/local/lib/node_modules/docsify-cli/node_modules/docsify
> opencollective postinstall

                         Thanks for installing docsify 🙏
                 Please consider donating to our open collective
                        to help us maintain this package.

          👉  Donate: https://opencollective.com/docsify/donate

+ docsify-cli@4.3.0
added 456 packages from 206 contributors in 32.827s

clipboard.png

安装结束后使用docsify -v查看是否安装成功：

docsify -v

docsify-cli version:
  4.3.0

2.2.2 初始化一个项目

首先须要建立一个项目目录：

mkdir docsify

进入项目目录后，使用docsify init ./来初始化一个项目：

cd docsify

docsify init ./

Initialization succeeded! Please run docsify serve ./
tree -a

.
├── .nojekyll
├── README.md
└── index.html

初始化成功后,docsify目录会生成以下几个文件：

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

.nojekyll文件很重要，若是网站部署到GitHub Pages时，必定要注意这个文件。

直接编辑 ./README.md 就能更新网站内容，固然也能够添加其余.md文件。

2.2.3 启动本地服务

终端输入docsify serve ./来启动服务：

docsify serve ./

Serving /Users/dragon/tmp/docsify now.
Listening at http://localhost:3000

而后浏览器打开http://localhost:3000就能看见效果。

clipboard.png

当修改文件保存后， docsify serve ./服务会自动实时更新。

3. 关于每一个页面和URL路径说明

若是须要建立多个页面，或者须要多级路由的网站，在docsify里也能很容易的实现。例如建立一个guide.md文件，那么对应的路由就是/#/guide。
若是你的目录结构以下：

-| ./
  -| README.md
  -| guide.md
  -| zh-cn/
    -| README.md
    -| guide.md

那么对应的访问页面将是:

./README.md        => http://domain.com
./guide.md         => http://domain.com/guide
./zh-cn/README.md  => http://domain.com/zh-cn/
./zh-cn/guide.md   => http://domain.com/zh-cn/guide

4. 侧边栏设置

默认状况下，侧边栏会根据当前文档的标题生成目录。

clipboard.png

4.1 定制侧边栏

首先须要在index.html文件中的window.$docsify添加loadSidebar: true,选项：

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

接着在项目根目录建立_sidebar.md文件，内容格式以下：

* [home1](home1)
* [home2](home2)
* [bar](bar/)
* [bar/a](bar/a)

clipboard.png

注：配置了loadSidebar后就不会生成默认的侧边栏了。

4.2 关于侧边栏_sidebar.md文件的说明

  • 若是只在根目录有一个_sidebar.md文件，那么全部页面都将使用这个一个配置，也就是全部页面的侧边栏都同样。
  • 若是一个子目录中有_sidebar.md文件，那么这个子目录下的全部页面将使用这个文件的侧边栏。
  • _sidebar.md的加载逻辑是从每层目录下获取文件，若是当前目录不存在该文件则回退到上一级目录。例如当前路径为/zh-cn/more-pages则从/zh-cn/_sidebar.md获取文件，若是不存在则从/_sidebar.md获取。

若是子目录有_sidebar.md,但你就想使用根目录的_sidebar.md，
可在index.html文件中的window.$docsify添加alias字段：

<script>
  window.$docsify = {
    loadSidebar: true,
    alias: {
      '/.*/_sidebar.md': '/_sidebar.md'
    }
  }
</script>

配置alias字段后，全部页面都会显示项目根目录_sidebar.md文件的配置做为侧边栏，子目录的_sidebar.md文件会失效。

4.3 显示页面目录(当前页面的标题)

定制的侧边栏仅显示了页面的连接。
还能够设置在侧边栏显示当前页面的目录(标题)。
须要在index.html文件中的window.$docsify添加subMaxLevel字段来设置：

<script>
  window.$docsify = {
    loadSidebar: true,
    subMaxLevel: 3
  }
</script>
<script src="//unpkg.com/docsify"></script>

clipboard.png

subMaxLevel说明：

subMaxLevel类型是number(数字)，表示显示的目录层级
注意：若是md文件中的第一个标题是一级标题，那么不会显示在侧边栏，如上图所示
值 说明
0 默认值，表示不显示目录
1 显示一级标题(h1)
2 显示1、二级标题(h1 ~ h2)
3 显示1、2、三级标题(h1 ~ h3)
n n是数字，显示1、2、....n 级标题(h1 ~ hn)

在md文件中标题的写法：

# 这是一级标题，对应HTML中<h1>标签

## 这是二级标题，对应HTML中<h2>标签

### 这是三级标题，对应HTML中<h3>标签

#### 这是四级标题，对应HTML中<h4>标签

4.3.1 页面的标题不在侧边栏目录显示

注意： 若是md文件的第一个标题是一级标题，那么默认已经忽略了。

当设置了 subMaxLevel 时，默认状况下每一个标题都会自动添加到目录中。若是你想忽略特定的标题，能够给它添加 {docsify-ignore} ：

# Getting Started

## Header {docsify-ignore}

该标题不会出如今侧边栏的目录中。

要忽略特定页面上的全部标题，你能够在页面的第一个标题上使用 {docsify-ignore-all} :

# Getting Started {docsify-ignore-all}

## Header

该页面全部标题都不会出如今侧边栏的目录中。

在使用时， {docsify-ignore} 和 {docsify-ignore-all} 都不会在页面上显示。

5. 导航栏配置

docsify默认是没有导航栏的，能够经过配置来显示导航栏。

5.1 在index.html中定义导航栏

若是导航的连接少，则能够直接在index.html文件直接定义导航栏，要注意连接要以#/开头：

<body>
  <nav>
    <a href="#/">项目</a>
    <a href="#/home1">home1</a>
    <a href="#/bar/a">bar/a</a>
  </nav>
</body>

clipboard.png

5.2 经过配置文件定义导航栏

首先须要在index.html文件中的window.$docsify添加loadNavbar: true,选项：

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

接着在项目根目录建立_navbar.md文件，内容格式以下：

* [home1](home1)
* [home2](home2)
* [bar](bar/)
* [bar/a](bar/a)

clipboard.png

注意：
1.若是使用配置文件来设置导航栏，那么在 index.html中定义的导航栏只有在定制的首页才会生效，其余页面会被覆盖。
2.若是只在根目录有一个 _navbar.md文件，那么全部页面都将使用这个一个配置，也就是全部页面的导航栏都同样。
3.若是一个子目录中有 _navbar.md文件，那么这个子目录下的全部页面将使用这个文件的导航栏。
4. _navbar.md的加载逻辑是从每层目录下获取文件，若是当前目录不存在该文件则回退到上一级目录。例如当前路径为 /zh-cn/more-pages则从 /zh-cn/_navbar.md获取文件，若是不存在则从 /_navbar.md获取。

5.3 导航栏嵌套

若是导航内容过多，能够写成嵌套的列表，会被渲染成下拉列表的形式：

* 根目录
  * [home1](home1)
  * [home2](home2)
  * [guide](guide)

* bar目录
  * [bar](bar/)
  * [a文件](bar/a)
  * [b文件](bar/b)

* foo目录
  * [one](foo/one)

clipboard.png

6. 设置封面

docsify默认是没有封面的，默认有个首页./README.md。
经过设置coverpage参数，能够开启渲染封面的功能。

首先须要在index.html文件中的window.$docsify添加coverpage: true选项：

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

接着在项目根目录建立_coverpage.md文件，内容格式以下：

![logo](_media/icon.svg)
# 个人文档网站
## 我的文档网站
> 一个神奇的文档网站生成巩固

* Simple and lightweight (~12kb gzipped)
* Multiple themes
* Not build static html files

[GitHub](https://github.com/docsifyjs/docsify/)
[Get Started](#quick-start)
[Get Started](#quick-start)

clipboard.png

注：一份文档只会在根目录下加载封面，其余页面或者二级目录下都不会加载。

6.1 自定义封面背景

目前的背景是随机生成的渐变色，每次刷新都会显示不一样的颜色。
docsify封面支持自定义背景色或者背景图，在_coverpage.md文档末尾添加：

<!-- 背景图片 -->
![](_media/bg.png)

<!-- 背景色 -->
![color](#2f4253)

clipboard.png

注意：
1.自定义背景配置必定要在 _coverpage.md文档末尾。
2.背景图片和背景色只能有一个生效.
3.背景色必定要是 #2f4253这种格式的。

6.2 把封面做为首页

配置了封面后，封面和首页是同时出现的，封面在上面，首页在下面。
经过设置onlyCover参数，可让docsify网站首页只显示封面，
原来的首页经过http://localhost:3000/#/README访问。

在index.html文件中的window.$docsify添加onlyCover: true,选项：

<script>
  window.$docsify = {
    coverpage: true,
    onlyCover: true,
  }
</script>
<script src="./docsify.min.js"></script>
经过此配置能够把 ./README.md文件独立出来，当成项目真正的README介绍文件。

6.3 多个封面

若是你的文档网站是多语言的，或许你须要设置多个封面。
例如你的文档目录结构以下

.
└── docs
    ├── README.md
    ├── guide.md
    ├── _coverpage.md
    └── zh-cn
        ├── README.md
        └── guide.md
        └── _coverpage.md

那么你能够在index.html文件中的window.$docsify这么配置:

window.$docsify = {
  coverpage: ['/', '/zh-cn/']
};

或者具体指名文件名:

window.$docsify = {
  coverpage: {
    '/': 'cover.md',
    '/zh-cn/': 'cover.md'
  }
};

7. 网站部署到GitHub Pages

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

一、 master分支
二、 master分支下的 docs目录
三、 gh-pages分支
一、若是你的文档直接是在项目根目录写的，那么可直接把代码推送到master分支上， GitHub Pages里选择 master branch.
2.若是你的文档是在master分支下的 docs/目录下编写的，那么可直接把代码推送到master分支上， GitHub Pages里选择 master branch/docs folder.

本例子项目是直接在根目录中编写的，因此GitHub Pages里选择master branch的方式部署。

首先在github网站上建立好仓库，而后终端打开项目目录：

git init
git add .
git commit -m 'docsify项目初始化'
git remote add origin https://github.com/username/docsify.git
git push --set-upstream origin master

代码推送到github上后，打开github的仓库，选择Settings -> GitHub Pages -> master branch -> save。

clipboard.png

clipboard.png

7.1 使用docsify的例子

https://spiritree.github.io/n...

https://ripperhe.com/awesome-...

8. 一些插件

8.1 搜索插件

全文搜索插件会根据当前页面上的超连接获取文档内容，在 localStorage 内创建文档索引。默认过时时间为一天，固然咱们能够本身指定须要缓存的文件列表或者配置过时时间。

<script>
    window.$docsify = {
      // 完整配置参数
      search: {
        maxAge: 86400000,               // 过时时间，单位毫秒，默认一天
        paths: [],                      // or 'auto'，匹配文件路径
        placeholder: 'Type to search',  // 搜索提示框文字， 支持本地化，例子在下面
        // placeholder: {
        //   '/zh-cn/': '搜索',
        //   '/': 'Type to search'
        // },
        noData: 'No Results!',          // 找不到结果文字提示，支持本地化，例子在下面
        // noData: {
        //   '/zh-cn/': '找不到结果',
        //   '/': 'No Results'
        // },
        depth: 2,                       // 搜索标题的最大程级, 1 - 6
      }
    }
  </script>
  <!-- 引入搜索模块 -->
  <script src="//unpkg.com/docsify/lib/plugins/search.js"></script>

8.2 评论插件Gitalk

Gitalk：一个现代化的，基于Preact和Github Issue的评论系统。
使用例子：

<link rel="stylesheet" href="//unpkg.com/gitalk/dist/gitalk.css">
<script src="//unpkg.com/docsify/lib/plugins/gitalk.min.js"></script>
<script src="//unpkg.com/gitalk/dist/gitalk.min.js"></script>
<script>
  const gitalk = new Gitalk({
    clientID: 'Github Application Client ID',
    clientSecret: 'Github Application Client Secret',
    repo: 'Github repo',
    owner: 'Github repo owner',
    admin: ['Github repo collaborators, only these guys can initialize github issues'],
    // facebook-like distraction free mode
    distractionFreeMode: false
  })
</script>

Gitalk具体使用教程：https://segmentfault.com/a/11...

docsify其余插件：https://docsify.js.org/#/zh-c...

8.3 样式插件

在网上找到一个样式：https://jhildenbiddle.github....

使用方法,在HTML文件中引入：

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

参考资料

docsify中文官网：https://docsify.js.org/#/zh-cn/

相关文章
相关标签/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公众号
   欢迎关注本站公众号,获取更多信息
联系我们 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程