使用docsify写文档写文档

在前面我们已经介绍了jekyll和sphinx,他们都是非常优秀的静态页面生成工具,但他们有一个共同的缺陷–需要先编译才能使用.

docsify走在了他们前面.它本质上就是一个可以渲染markdown资源的单页应用,我们只需要写markdown然后挂在http服务器上就可以了.它的主要优势是:

不用编译
前端渲染,只占用阅读者机器的资源

适用场景

docsify基本上固定样式结构.它会有一个固定的侧栏,一个固定的内容页,一个可选的封面页,一个可选的顶部导航栏.因此一些复杂页面的就不太合适了. 个人总结最适合的使用场景有:

写网络书籍
写软件的使用文档

docsify文档项目的基本构成

大致构成如下:

root/
    |- index.html (入口文件)
    |- _sidebar.md (侧边栏定义)
    |- README.md (项目首页)
    |- 内容页markdown/...
    |- .nojekyll (如果挂在github page上则需要有)
    |- favicon.ico (可选,标签图标)
    |- _navbar.md (可选,顶部导航栏)
    |- _coverpage.md (可选,封面页)

基本样式

入口`index.html`

index.html是项目的入口,所有的插件,配置都在其中定义,它没有实质内容,只是入口.下面是一个例子

<!DOCTYPE html>
<html lang="en">

<head>
<meta charset="UTF-8">

<title>Tutorial For SQL</title>
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
<meta name="description" content="Description">
<meta name="viewport"
    content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
<link rel="shortcut icon" type="image/x-icon" href="favicon.ico">
<link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/vue.css">
<link rel="stylesheet" href="css/sidebar.css">
<link rel="stylesheet" href="https://unpkg.com/docsify-toc@1.0.0/dist/toc.css">
<!-- <link rel="stylesheet" href="css/vue.css?v=1.1.0"> -->
</head>

<body>
<div id="app"></div>
<script>
    window.$docsify = {
    name: 'Tutorial For SQL',
    loadSidebar: true,
    // maxLevel: 6,
    repo: 'https://github.com/hsz1273327/TutorialForSQL',
    logo: '/images/sql.svg',
    subMaxLevel: 1,
    auto2top: true,
    alias: {
        '/.*/_sidebar.md': '/_sidebar.md'
    },
    toc: {
        scope: '.markdown-section',
        headings: 'h1, h2, h3, h4',
        title: '快速跳转',
    },
    pagination: {
        previousText: '上一章节',
        nextText: '下一章节',
        crossChapter: true,
        crossChapterText: true,
    },
    search: {
        maxAge: 86400000, // 过期时间，单位毫秒，默认一天
        paths: [], // or 'auto'
        placeholder: 'Type to search',

        // 支持本地化
        placeholder: {
        '/zh-cn/': '搜索',
        '/': 'Type to search'
        },

        noData: 'No Results!',

        // 支持本地化
        noData: {
        '/zh-cn/': '找不到结果',
        '/': 'No Results'
        },

        // 搜索标题的最大程级, 1 - 6
        depth: 2
    },
    copyCode: {
        // buttonText : 'buttonText:String',
        // errorText  : 'errorText:String',
        // successText: 'successText:String'

        buttonText: {
        '/zh-cn/': '点击复制',
        '/ru/': 'Скопировать в буфер обмена',
        '/de-de/': 'Klicken Sie zum Kopieren',
        '/es/': 'Haga clic para copiar',
        '/': 'Copy to clipboard'
        },
        errorText: {
        '/zh-cn/': '错误',
        '/ru/': 'ошибка',
        '/': 'Error'
        },
        successText: {
        '/zh-cn/': '复制',
        '/ru/': 'Скопировано',
        '/de-de/': 'Kopiert',
        '/es/': 'Copiado',
        '/': 'Copied'
        }
    }
    }
</script>

<!-- CDN files for docsify.-->
<!-- <script src="js/docsify.js?v=1.1.0"></script> -->
<script src="//cdn.jsdelivr.net/npm/docsify@latest/lib/docsify.min.js"></script>
<!-- CDN files for docsify plugins.-->
<script src="//cdn.jsdelivr.net/npm/docsify-sidebar-collapse/dist/docsify-sidebar-collapse.min.js"></script>
<script src="https://unpkg.com/docsify-toc@1.0.0/dist/toc.js"></script>
<script src="//cdn.jsdelivr.net/npm/docsify-copy-code"></script>
<script src="//unpkg.com/docsify-pagination/dist/docsify-pagination.min.js"></script>
<script src="//unpkg.com/docsify/lib/plugins/search.js"></script>
<!-- CDN files for code highlight such as docsify-katex etc.-->
<script src="//cdn.jsdelivr.net/npm/docsify-katex@latest/dist/docsify-katex.js"></script>
<!-- or <script src="//cdn.jsdelivr.net/gh/upupming/docsify-katex/dist/docsify-katex.js"></script> -->
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/katex@latest/dist/katex.min.css" />
<script src="//unpkg.com/prismjs/components/prism-python.min.js"></script>
<script src="//unpkg.com/prismjs/components/prism-makefile.min.js"></script>
<script src="//unpkg.com/prismjs/components/prism-sql.min.js"></script>
<script src="//unpkg.com/prismjs/components/prism-json.min.js" async></script>
</body>

</html>

和一般的html一样,我们在其中导入依赖的css和js文件,但不同的是我们需要定义window.$docsify这个对象,这就是docsify的配置项.比较常用的几个:

name,主要需要和html中的title一致
loadSidebar是否加载侧边栏
repogithub项目的地址
logologo图,一般用svg格式
subMaxLevel侧边栏最大深度

其他的插件和配置我们后面介绍

侧边栏与内容导航

侧边栏_sidebar.md的定义方法类似下面:

- [回到博客](http://blog.hszofficial.site/)
- [SQL简介](README.md)
- [DDL语句](DDL语句.md)
- [DML语句](DML语句/README.md)
  - [简单的增删改查](DML语句/简单的增删改查.md)
  - [查询语句扩展](DML语句/查询语句扩展.md)
  - [聚合查询](DML语句/聚合查询.md)
  - [窗口查询](DML语句/窗口查询.md)
  - [条件分支CASE语句](DML语句/条件分支CASE语句.md)
  - [多表查询](DML语句/多表查询.md)
  - [关联子查询](DML语句/关联子查询.md)
  - [复杂HAVING语句](DML语句/复杂HAVING语句.md)
  - [复杂EXISTS语句](DML语句/复杂EXISTS语句.md)
  - [使用view保存查询](DML语句/使用view保存查询.md)
- [DCL语句](DCL语句.md)
- [收尾](收尾.md)

我们通过缩进确定目录的层级关系.

对应的设置是subMaxLevel,它会控制文章中在侧边栏里展示的目录最大层级,建议设置为0配合toc插件做文章内导航.

文章内导航

我们可以通过使用插件docsify-toc做文章内的导航和跳转.它可以在右上角

的使用方式就是在index.html中加入:

<script src="https://unpkg.com/docsify-toc@1.0.0/dist/toc.js"></script>
<link rel="stylesheet" href="https://unpkg.com/docsify-toc@1.0.0/dist/toc.css">

它可以做如下配置:

 toc: {
    scope: '.markdown-section',
    headings: 'h1, h2, h3, h4, h5, h6',
    title: 'Table of Contents',
  },

建议设置headings为'h1, h2, h3, h4'

侧边栏折叠

docsify的侧边栏默认是不能折叠的这就很僵硬,我们可以通过导入插件docsify-sidebar-collapse来解决

<script src="//cdn.jsdelivr.net/npm/docsify-sidebar-collapse/dist/docsify-sidebar-collapse.min.js"></script>

这个库使用的时候有以下几个约束:

_sidebar.md每行之间不能有空行.
每个markdown文件必须以#作为标题,也就是有h1标签在开头,否则会出现点击后退回最初状态的情况.

如果觉得看不出哪些是折叠的哪些是没折叠的可以在下面两个css中调一个:

箭头型图标指示折叠

  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify-sidebar-collapse/dist/sidebar.min.css"/>

文件夹图标指示折叠

  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify-sidebar-collapse/dist/sidebar-folder.min.css" />

注意:这个插件会将所有非指向.md文件的都作为目录处理折叠起来,因此如果内容很少最好不要折叠,会看起来很单薄.

主题

docsify项目可以变换主题,只需要修改index.html中 <link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/vue.css">为需要的主题css即可

其他实用插件

docsify-pagination

这个插件可以在内容页底部添加一对按钮用于跳转到上一篇或下一篇.在index.html中添加下面代码使用

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

它可以配置为:

  pagination: {
      previousText: '上一章节',
      nextText: '下一章节',
      crossChapter: true,
      crossChapterText: true,
  },

search

这个插件用于在浏览器端构造全文搜素的索引..在index.html中添加下面代码使用
```
  <script src="//unpkg.com/docsify/lib/plugins/search.js"></script>
```
它可以配置为:
```
  search: 'auto',
```

代码高亮和语法解析

剩下来的就是code标签的功能了.

latex语法解析生成公式

  <script src="//cdn.jsdelivr.net/npm/docsify-katex@latest/dist/docsify-katex.js"></script>
  <!-- or <script src="//cdn.jsdelivr.net/gh/upupming/docsify-katex/dist/docsify-katex.js"></script> -->
  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/katex@latest/dist/katex.min.css" />

常用编程语言高亮

可以去https://unpkg.com/browse/prismjs@1.15.0/components/查看,看到需要的写入index.html中就可以了

docsify-copy-code

这个插件可以在代码栏添加一个按钮用于将代码复制到本地剪贴板.在index.html中添加下面代码使用

  <script src="//cdn.jsdelivr.net/npm/docsify-copy-code"></script>

它可以配置为:

  copyCode: {
      // buttonText : 'buttonText:String',
      // errorText  : 'errorText:String',
      // successText: 'successText:String'
      buttonText: {
          '/zh-cn/': '点击复制',
          '/ru/': 'Скопировать в буфер обмена',
          '/de-de/': 'Klicken Sie zum Kopieren',
          '/es/': 'Haga clic para copiar',
          '/': 'Copy to clipboard'
      },
      errorText: {
          '/zh-cn/': '错误',
          '/ru/': 'ошибка',
          '/': 'Error'
      },
      successText: {
          '/zh-cn/': '复制',
          '/ru/': 'Скопировано',
          '/de-de/': 'Kopiert',
          '/es/': 'Copiado',
          '/': 'Copied'
      }
  }

使用docsify写文档

使用docsify写文档写文档

适用场景

docsify文档项目的基本构成

入口`index.html`

侧边栏与内容导航

文章内导航

侧边栏折叠

主题

其他实用插件

代码高亮和语法解析

POST TAGS

POST Category

使用docsify写文档写文档

适用场景

docsify文档项目的基本构成

入口index.html

侧边栏与内容导航

文章内导航

侧边栏折叠

主题

其他实用插件

代码高亮和语法解析

POST TAGS

POST Category

入口`index.html`