MENU

docsify - 搭建美观的文档网站

November 13, 2018 • 建站笔记

docsify 是一个动态生成文档网站的工具,可以将.md文件以wiki的形式展示给读者,可以用于制作技术文档、用户手册、wiki等。可以部署于主机、VPS、Github、静态云存储(例如阿里云OSS)。

demo1

新手包

黑猫提供已经基本设置好docsify的压缩包,下载解压至网站根目录即可使用。

与下面的教程配合食用。

在VPS/主机上搭建

首先搭建网站环境(LNMP)、设置域名解析等,这里以宝塔面板为例.

1. 新建index.html文件

在网站根目录新建空白文件,文件名为index.html
buildindex

拷贝以下内容

<!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. 上传.md文件

假设你的目录结构如下:

-| 域名根目录/
  -| README.md
  -| guide.md
  -| zh-cn/
    -| README.md
    -| guide.md

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

网站根目录/README.md        => http://domain.com
网站根目录/guide.md         => http://domain.com/guide
网站根目录/zh-cn/README.md  => http://domain.com/zh-cn/
网站根目录/zh-cn/guide.md   => http://domain.com/zh-cn/guide

上传默认的访问内容README.md文件,然后访问域名就可以看到效果!至此,docsify已基本搭建完成。
注意在宝塔面板中,为了安全,默认配置禁止访问README.md,所以需要将其从禁止访问的文件列表删除,如下图:
readmebt

3. 设置侧边栏导航

首先在index.html中添加一行配置:loadSidebar: true,如下图所示:
siba

接着创建 _sidebar.md 文件,填写类似下面的内容:

* **分隔1:**
* [注释1](foler/)
* [注释2](文件名.md)
* **分隔2:**

4. (可选)设置封面

在index.html中添加一行配置:coverpage: true
!> 注意,多个配置之间要写逗号,如下图所示

set

接着创建_coverpage.md文件,填写类似下面的内容:

![logo](_media/icon.svg)

# docsify

> A magical documentation site generator.

* Simple and lightweight (~12kb gzipped)
* Multiple themes
* Not build static html files

[GitHub](https://github.com/docsifyjs/docsify/)
[Get Started](#quick-start)

如果要自定义背景,则可以在文件末尾继续添加:

<!-- 背景图片 -->

![](_media/bg.png)

<!-- 背景色 -->

![color](#f0f0f0)

5. (可选)自动目录

在index.html中添加配置maxLevel: 2,意思是二级标题会自动生成目录。

6. (可选)文档标题

文档标题会显示在侧边栏顶部。在index.html中添加配置name: '文档标题'

7. (可选)开启搜索

在index.html中添加配置search: 'auto'
在js调用中添加<script src="//unpkg.com/docsify/lib/plugins/search.js"></script>

其他自定义项

官方文档提供更加丰富的自定义配置,请参阅官方文档:docsify.js.org/

静态资源加速(重要)

注意到html中调用的都是外部的js和css,中国大陆访问比较慢

将js、css文件放入本地,或者放入云存储/CDN中,加速访问

首先通过访问外部域名获得js/css文件:
例如:
js文件:https://unpkg.com/docsify/lib/docsify.min.js
css文件:https://unpkg.com/docsify/themes/vue.css
搜索功能js文件:https://unpkg.com/docsify/lib/plugins/search.js
或者通过上文黑猫提供的静态资源下载包获得。
将静态资源下载至本地static文件夹,再将index.html中调用的外部链接替换为本地资源,如下图所示:
stati

部署至Github

可以由Github托管,节省服务器开支。请参照官方文档

部署至阿里OSS

我们在《国内对象存储免费额度对比》中提到,阿里云OSS香港提供5G免费存储和流量,所以我们可以将文档免费部署,比github访问更快哦!

只需要在阿里云控制台,开通OSS存储,选择香港区,创建公开存储桶,打开“静态页面”功能,将docsify文件上传即可。阿里云OSS提供域名,也可以绑定自定义域名。
oss

最后编辑于: May 15, 2019
Archives Tip
QR Code for this page
Tipping QR Code
Leave a Comment

已有 7 条评论
  1. 资源包已经挂了

    1. @常阳岁月感谢! 下载链接已更新。OωO

  2. 氢气球 氢气球

    侧边栏怎么设置?md中表格怎么展示成全边框样式的?

    1. @氢气球文章里有写如何创建侧边栏(sidebar)。如果看不懂的话就下载新手包,套用格式。

  3. mengtongtong mengtongtong

    请问能设多个侧边栏(sidebar)文件吗?根据点击首页不同按钮,载入不同的侧边栏

    1. @mengtongtong原版肯定不可以。如果想实现,可以自己魔改。或者曲线救国,通过多个子域名实现?

    2. mengtongtong mengtongtong

      @黑猫您的意思是像官方文档那种吗?我看有中英法各种语言的,页面切换的时候就是子域名在变化。