· 2020-02-26 · / / Essay

[Tuto]docsify在线文档生成

docsify 是一个动态生成文档网站的工具，不同于 GitBook、Hexo 等，它不会将 .md 转成 .html 文件，所有转换工作都在运行时进行。

1 配置docsify

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

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

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

docsify -v

docsify-cli version:
  x.x.x

2 初始化一个文档

① 手动创建index.html并引入docsify文件

只需要创建一个index.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文件：

## I'm homepage
This is my homepage

② 自动初始化

首先需要创建一个项目目录：
mkdir docsify

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

cd docsify

docsify init ./

Initialization succeeded! Please run docsify serve ./

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

  • index.html入口文件
  • README.md会做为主页内容渲染
  • nojekyll用于阻止 GitHub Pages 会忽略掉下划线开头的文件
    nojekyll文件很重要，如果网站部署到GitHub Pages时，一定要注意这个文件。

直接编辑 ./README.md 就能更新网站内容，当然也可以添加其他.md文件。

3 本地预览

① http-server服务方式

用http-server启动服务 (可在终端输入npm install http-server -g来安装http-server)，在浏览器中输入http://127.0.0.1:8080即可浏览效果。

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

② docsify serve方式

docsify serve是一个本地服务器，通过 docsify serve 可以方便地预览效果，而且提供 LiveReload 功能。

启动docsify serve (./docs根目录下cmd)：

docsify serve ./

Serving F:\...\...\docs now.
Listening at http://localhost:3000

终止docsify serve：
Ctrl+C

默认访问端口：
http://localhost:3000

4 文档部署

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

- master分支
- master分支下的docs目录
- gh-pages分支
  • 如果你的文档直接是在项目根目录写的，那么可直接把代码推送到master分支上， GitHub Pages里选择master branch;
  • 如果你的文档是在master分支下的docs/目录下编写的，那么可直接把代码推送到master分支上，GitHub Pages里选择master branch/docs folder。

5 文档编写/自定义

5-1 定制侧边栏

默认情况下，侧边栏会根据当前文档的标题生成目录。也可以设置文档链接，通过 Markdown 文件生成，此时需要手动创建 _sidebar.md 文件:

* RaindropFX Pro
	* [2.0.0](RaindropFXPro200)
	* [1.5.0](RaindropFXPro150)
	* [1.0.1](RaindropFXPro101)
	* [Revision History](RaindropFXProHistory)
	* [FAQ](RaindropFXProFAQ)
* [RaindropFX Lite](RaindropFXLite)
* [SplineMesher](SplineMesher)
  • 如果只在根目录有一个_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文件会失效。

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)
  • 如果使用配置文件来设置导航栏，那么在index.html中定义的导航栏只有在定制的首页才会生效，其他页面会被覆盖。
  • 如果只在根目录有一个_navbar.md文件，那么所有页面都将使用这个一个配置，也就是所有页面的导航栏都一样。
  • 如果一个子目录中有_navbar.md文件，那么这个子目录下的所有页面将使用这个文件的导航栏。
  • _navbar.md的加载逻辑是从每层目录下获取文件，如果当前目录不存在该文件则回退到上一级目录。例如当前路径为/zh-cn/more-pages则从/zh-cn/_navbar.md获取文件，如果不存在则从/_navbar.md获取。

如果导航内容过多，可以写成嵌套的列表，会被渲染成下拉列表的形式：

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

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

5-3 多级文档

如果需要创建多个页面，或者需要多级路由的网站，在 docsify 里也能轻松实现。

假设你的目录结构如下：

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

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

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

5-4 隐藏标题

当设置了 subMaxLevel 时，默认情况下每个标题都会自动添加到目录中。如果你想忽略特定的标题，可以给它添加 {docsify-ignore} ：

# Getting Started

## Header {docsify-ignore}

5-5 搜索配置

全文搜索插件会根据当前页面上的超链接获取文档内容，在 localStorage 内建立文档索引。默认过期时间为一天，当然我们可以自己指定需要缓存的文件列表或者配置过期时间。

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

5-6 评论插件Gitalk

一个现代化的，基于Preact和Github Issue的评论系统。配置完成后需要登录自己的账号点开一次对应文档才会自动在项目中生成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>

5-7 更改样式

在HTML文件中引入样式表：

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

Categories Essay Tools Static Anime

Tags Essay


Home Back to Home

上一篇->[Tool]RaindropFX Pro update 2.0.0


下一篇->[Static]New Year 2020