使用Docsify做文档网站的详细配置教程

作者：xhemj

没错，它叫Docsify。

xhemj的文档中心就是用这个写的

开源地址：https://github.com/docsifyjs/docsify/

官方Demo：https://docsify.js.org/

官方说明

Docsify

A magical documentation site generator.

Simple and lightweight (~21kB gzipped)

No statically built html files

Multiple themes

Docsify

一个神奇的文档站点生成器。

简单轻巧（~21kB）

没有生成静态的html文件

主题丰富

安装

本地搭建

如果你想在本地搭建：

npm安装：

npm i docsify-cli -g

初始化：

docsify init ./docs

本地预览：

docsify serve docs

进入http://localhost:3000就能看到效果咯！

托管在网上

如果你想在托管在网上：

新建一个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="//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>

CDN的选择

CDN可以选择：

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

<script src="//cdnjs.cloudflare.com/ajax/libs/docsify/4.11.2/docsify.min.js"></script>

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

这样就可以看到一个最基本的网页啦！

如何写文章

只需用Markdown语法写好一个.md的文章放在根目录或子目录后就会自动识别了。

我自己测试好像用html的也可以，直接把后缀名改成.md，但效果可能不太好。

文章链接对应：

/README.md  =>  domain.com/#/

/hello.md  =>  domain.com/#/hello

/hello/hi.md  =>  domain.com/#/hello/hi

如本教程文章Markdown文件为：https://gitee.com/xhemj/books/raw/master/p/How-to-Use-Docsify.md

渲染成：https://xhemj.gitee.io/books/#/p/How-to-Use-Docsify

个性化

自定义加载文字

只需在index.html中新增：

<div id="app">Please wait...</div>

自定义侧边栏

只需在index.html中新增：

<script>

  window.$docsify = {

    loadSidebar: true

  }

</script>

后创建一个文件叫做_sidebar.md，将你的文件输入进去：

* [Home](/)

* [Guide](guide.md)

_sidebar.md的加载逻辑是从每层目录下获取文件，如果当前目录不存在该文件则回退到上一级目录。

例如当前路径为/zh-cn/more-pages则从/zh-cn/_sidebar.md获取文件，如果不存在则从/_sidebar.md获取。

注意，如果是托管在网上，请在文件根目录新增名叫.nojekyll的空文件。

为了更好地SEO，您可以在每个文件后面自定义标题：

* [Home](/)

* [Guide](guide.md "The greatest guide in the world")

默认情况下会自动根据文章标题生成目录，如果不想要，可以再index.html中新增：

<script>

  window.$docsify = {

    loadSidebar: true,

    subMaxLevel: 2

  }

</script>

subMaxLevel: 2表示只显示h1~h2的标题，对应#和##。

如果你想忽略某个标题，则可以在文章中新增{docsify-ignore}：

# Getting Started

## Header {docsify-ignore}

如果想忽略全部的标题，则可以新增{docsify-ignore-all}：

# Getting Started {docsify-ignore-all}

## Header

表示忽略{docsify-ignore-all}下的全部标题

{docsify-ignore-all}和{docsify-ignore}在正文中都不会显示

自定义导航栏

写法一：

在index.html中新增：

<body>

  <nav>

    <a href="#/">EN</a>

    <a href="#/zh-cn/">中文</a>

  </nav>

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

</body>

所有路径都必须用#/来书写

写法二：

在根目录新增_navbar.md文件：

写法同_sidebar.md

* [En](/)

* [chinese](/zh-cn/)

你也可以按照如下来写多级导航栏：

* Getting started

  * [Quick start](quickstart.md)

  * [Writing more pages](more-pages.md)

  * [Custom navbar](custom-navbar.md)

  * [Cover page](cover.md)

* Configuration

  * [Configuration](configuration.md)

  * [Themes](themes.md)

  * [Using plugins](plugins.md)

  * [Markdown configuration](markdown.md)

  * [Language highlight](language-highlight.md)

_navbar.md的加载逻辑是从每层目录下获取文件，如果当前目录不存在该文件则回退到上一级目录。

例如当前路径为/zh-cn/more-pages则从/zh-cn/_navbar.md获取文件，如果不存在则从_navbar.md获取。

封面

设置：

window.$docsify = {

    coverpage: true,

}

后再根目录创建_coverpage.md

输入内容就可以显示在封面了

效果见https://xhemj.gitee.io/books/

主题颜色

设置：

window.$docsify = {

    themeColor: '#c30aff',

}

#c30aff就是主题的颜色了

外链打开方式

设置：

window.$docsify = {

	externalLinkTarget: '_blank',

}

_blank表示在新标签页中打开

插件

表情插件

先在在index.html中新增：

<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/emoji.min.js"></script>

我自己测试是我上面推荐的三个CDN都可以使用

即可输入

:100: =>