docsify 学习笔记2019-03-28

2019-03-28 本文已影响0人小沙坨

一、docsify介绍

1.1docsify介绍

（1）docsify是一个文档生成工具，它直接加载 Markdown 文件并动态渲染，同时还可以生成封面页。
（2）不同于 GitBook、Hexo 的地方是它不会生成将 .md 转成 .html 文件，所有转换工作都是在运行时进行。
（3）docsify是由现饿了么前端团队@elemeFE的cinwell.li编写的一套文档站点生成框架，github上已有3k+ star，这款框架和其他框架如gitbook等相比，最大的区别就在于docsify不是静态生成html，而通过动态请求markdown编译生成html。

1.2docsify特点

无需构建无需编译，写完markdown文档直接发布
容易使用并且轻量 (~18kB gzipped)
智能的全文搜索
提供多套主题
丰富的 API
支持 Emoji
兼容 IE10+
支持 SSR (example)
快速上手

1.3文档规范的好处

清晰、好看、方便维护

1.4官方网址

对于具体的学习资料，大家可以参考官方网站。

https://docsify.js.org/#/zh-cn/quickstart

1.5其它主流

目前市面上有大致这么几款主流的文档生成站点，分别为docsify、gitbook、Phenomic等，可帮助用户快速搭建文档站点。

二、使用教程

2.1root安装

推荐安装 docsify-cli 工具，可以方便创建及本地预览文档网站。在安装docsify-cli之前需要确保您首先安装node。

npm i docsify-cli -g

2.2普通用户下初始化项目

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

docsify init ./docs

2.3开始写文档

初始化成功后，可以看到 ./docs 目录下创建的几个文件

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

直接编辑 docs/README.md 就能更新网站内容，当然也可以写多个页面。

2.4本地预览网站

运行一个本地服务器通过 docsify serve 命令可以方便的预览效果，而且提供 LiveReload 功能，可以让实时的预览。默认访问 http://localhost:3000 。

docsify serve docs

如果需要启动其他端口，可以直接在后面增加-p 4000表示启动端口为4000

更多命令行工具用法，参考docsify-cli文档。

2.5手动初始化

如果不喜欢 npm 或者觉得安装工具太麻烦，我们其实只需要直接创建一个 index.html 文件。

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>

2.6侧边栏

为了有侧边栏，那么你可以创建你自己的_sidebar.md：

首先，你需要设置loadSidebar为true。详细信息可在配置段落中找到。

2.6.1 index.html配置如下所示：

<script>

  window.$docsify = {

    loadSidebar: true

  }

</script>

<script src="//unpkg.com/docsify/lib/docsify.min.js"></script>

2.6.2侧边栏md配置

创建_sidebar.md：

Home
Guide

三、demo示例

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">

  <!-- Theme: Simple -->

  <!--

  <link rel="stylesheet" href="https://unpkg.com/docsify-themeable/dist/css/theme-simple.css">

  -->

  <link rel="stylesheet" href="assets/theme-simple.css">

  <!-- Custom theme stylesheet -->

  <link rel="stylesheet" href="assets/theme-custom.css">

  <style>

        nav.app-nav li ul {

            min-width: 100px;

        }

  </style>

</head>

<body>

  <div id="app"></div>

  <script>

    window.$docsify = {

      //定义路由别名，可以更自由的定义路由规则。 支持正则。

      alias: {

            '/.*/_sidebar.md': '/_sidebar.md'

      },

      // 加载 _sidebar.md,加载自定义侧边栏

      loadSidebar: true,

      //加载自定义导航栏

      loadNavbar: false,

      // 强制悬停,切换页面后是否自动跳转到页面顶部。

      auto2top: true,

      // 调整副标题的级数

      subMaxLevel: 2,

      // 替换主题色

      themeColor: '#4CAF50',

      themeable: {

          readyTransition : true, // default

          responsiveTables: true  // default

      },

      showLevel: true,

      //文档标题，会显示在侧边栏顶部。

      name: '',

      //配置仓库地址或者 username/repo 的字符串，会在页面右上角渲染一个 GitHub Corner 挂件。

      repo: '',

      //禁用 emoji 解析

      noEmoji: true,

      tocLevel: 6,

      //搜索配置项

      search: {

        maxAge: 86400000, // 过期时间，单位毫秒，默认一天

        paths: 'auto', // or 'auto'

        placeholder: '搜索',

        noData: '找不到结果',

        // 搜索标题的最大程级, 1 - 6

        depth: 4

      },

      pagination: {

        previousText: '上一章节',

        nextText: '下一章节',

      }

    }

  </script>

  <script src="//unpkg.com/docsify/lib/docsify.min.js"></script>

  <script src="//unpkg.com/docsify/lib/plugins/search.min.js"></script>

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

  <script src="//unpkg.com/docsify-copy-code"></script>

  <script src="//unpkg.com/prismjs/components/prism-sql.min.js"></script>

  <script src="//unpkg.com/prismjs/components/prism-http.min.js"></script>

  <script src="//unpkg.com/prismjs/components/prism-json.min.js"></script>

  <script src="//unpkg.com/prismjs/components/prism-bash.min.js"></script>

  <script src="//unpkg.com/prismjs/components/prism-java.min.js"></script>

  <script src="//unpkg.com/prismjs/components/prism-markdown.min.js"></script>

  <script src="//unpkg.com/prismjs/components/prism-nginx.min.js"></script>

  <script src="//unpkg.com/prismjs/components/prism-php.min.js"></script>

  <script src="//unpkg.com/prismjs/components/prism-python.min.js"></script>

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

  <!-- docsify-themeable -->

  <script src="https://unpkg.com/docsify-themeable"></script>

</body>

</html>