黑猫

docsify - 搭建美观的文档网站
docsify 是一个动态生成文档网站的工具,可以将.md文件以wiki的形式展示给读者,可以用于制作技术文档、用...
扫描右侧二维码阅读全文
13
2018/11

docsify - 搭建美观的文档网站

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

接着创建 _sidebar.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

Last modification:November 13th, 2018 at 09:49 pm
If you think my article is useful to you, please feel free to appreciate

Leave a Comment