Docsify 可动态生成文档网站

2020-03-10 本文已影响0人 acc8226

一个神奇的文档网站生成工具。

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

这将非常实用，如果只是需要快速的搭建一个小型的文档网站，或者不想因为生成的一堆 .html 文件“污染” commit 记录，只需要创建一个 index.html 就可以开始写文档而且直接部署在 GitHub Pages。

查看快速开始了解详情。

初始化项目

如果想在项目的 ./docs 目录里写文档，直接通过 init 初始化项目。

docsify init ./docs

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

多页文档
例如创建一个 guide.md 文件，那么对应的路由就是 /#/guide。

启动项目

python -m SimpleHTTPServer 3000
# or
python3 -m http.server 3000

定制侧边栏

为了获得侧边栏，您需要创建自己的_sidebar.md

* [首页](/)
* [后端用到](not_front/123)

文件所在路径

README.md
not_front/123.md

image.png

index.html 信息

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Document</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="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/lib/themes/vue.css">
</head>
<body>
  <div id="app"></div>
  <script>
    window.$docsify = {
      loadSidebar: '_sidebar.md',
      subMaxLevel: 3
    }
  </script>
  <script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
</body>
</html>

官方地址的压缩版

压缩版 css
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/lib/themes/vue.css">

压缩版 js
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>

其他主题
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css">
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/dark.css">

相关插件

代码高亮

docsify内置的代码高亮工具是 Prism。Prism 默认支持的语言如下：

Markup - markup, html, xml, svg, mathml, ssml, atom, rss
CSS - css
C-like - clike
JavaScript - javascript, js

添加额外的语法支持需要通过CDN添加相应的语法文件 :

<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-php.min.js"></script>

copy 插件

  <script>
    window.$docsify = {
      copyCode: {
        buttonText: {
          '/'      : '点击复制'
        },
        errorText: {
          '/': '错误',
        },
        successText: {
          '/'      : '已复制'
        }
      }
    }
  </script>

字数统计

这是一款为docsify提供文字统计的插件. @827652549提供

它提供了统计中文汉字和英文单词的功能，并且排除了一些markdown语法的特殊字符例如*、-等

Add JS

<script src="//unpkg.com/docsify-count/dist/countable.js"></script>

Add settings

window.$docsify = {
  count:{
    countable:true,
    fontsize:'0.9em',
    color:'rgb(90,90,90)',
    language:'chinese'
  }
}

docsify-themeable 主题的使用