用Docsify轻松生成文档网站

当你有了一个全新的项目,但是有着大量的帮助文档和技术细节时,Github的wiki可能就不是那么好用了,而且很有可能我们需要一个单独的网站来展示项目和技术文档,庞大的技术文档库如何生成一个网站呢?

面对这样的需求,很多的企业选择了自建wiki或者类似的系统,但是这样需要占用一部分服务器资源,而很多的开发者并没有精力去维护一个单独的文档网站。直到Docsify的出现。

Docsify的项目地址在这里,这个项目的文档网站也是通过其本身生成的。

本地环境&&初始化

Docksify提供了一个cli工具用于初始化项目&实时预览,这个cli是基于Nodejs的,也就是意味着先要在本地安装nodejs,这一部分非常简单,本篇文章重点放在Docsify的cli和基础的使用部分。

在安装完成Nodejs环境之后,只需要在命令行中

npm i docsify-cli g

接下来切换到项目的根目录,如果是已有项目,并且需要在./docs中写文档,可以

docsify init ./docs

如果只是单纯的文档项目,我们可以直接

docsify init .

是不是很像git init?初始化完成之后我们可以在相应目录下看到下列文件

  • index.html 记录自定义配置,同时也是入口文件
  • README.md 主页面内容
  • .nojekyll 阻止Github Pages忽略下划线开头的文件

编写&&实时预览

Docsify提供了一个LiveReload的server可以让我们实时看到更改的效果,降低了学习和调试的成本,默认的端口是3000,即http://localhost:3000

docsify serve docs

扩展语法

我把这个部分放在前面,是因为这部分的扩展语法算是经常会使用的,而且handsome主题也在此基础上进行了一定的扩展。

!> 一段重要的内容,可以和其他 **Markdown** 语法混用。

Snipaste_2019-04-19_22-53-13.png

?> _TODO_ 完善示例

Snipaste_2019-04-19_22-53-20.png

自定义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>

配置项的种类算是非常丰富的,你可以简单地通过一些配置项的变更,实现高度的自定义

  • repo 可以在右上角渲染Github Corner挂件
  • maxLevel 配置最大支持渲染的标题层级,默认为6
  • loadNavbar 加载自定义导航栏配置
  • loadSidebar 加载自定义侧边栏配置
  • auto2top 切换页面后跳转到顶部
  • coverpage 启用封面页
    还有很多,可以参考官方文档

侧边栏与导航栏

侧边栏

开启了loadSidebar我们就可以使用_sidebar.md配置侧边栏,这里是一个简单的例子

- **快速开始**
 - [快速开始](快速开始.md)
- **进阶用法**
 - [进阶用法](进阶用法.md)
 - [小技巧](小技巧.md)

还可以设置subMaxLevel开始目录功能,对于文档中的某些标题,我们可以选择忽略

# Getting Started

## Header {docsify-ignore}

该标题不会出现在侧边栏的目录中。

或者直接忽略所有标题

# Getting Started {docsify-ignore-all}

## Header

该标题不会出现在侧边栏的目录中。

在使用时, {docsify-ignore} 和 {docsify-ignore-all} 都不会在页面上呈现。

导航栏

你可以直接在index.html中定义导航栏,不过我更推荐在_navbar.md中定义,这样修改起来更加直观。
这里有一个简单的例子

* [En](/)
* [中文](/zh-cn/)

如果写成了嵌套列表,docsify会帮你渲染成下拉列表

封面

开启coverpage选项后,docsify会从_coverpage.md中读取配置

![logo](logo.svg)

# 炮兵小队

> 可能是最理想的校园网工具

* 全面支持下一代网际协议
* 高效代码 轻量工具
* 钻石品质线路

[访问网站](https://issacc.bid ':target=_blank')
[开始使用](快速开始)

默认的背景是随机生成的渐变色,自定义背景图或背景色可以

![](bg.png)
![](#fff)

更换主题

Docsify现有三套主题可选,只需要在index.html中替换相应的css文件

  <link rel="stylesheet" href="//unpkg.com/docsify/themes/vue.css">
  <link rel="stylesheet" href="//unpkg.com/docsify/themes/buble.css">
  <link rel="stylesheet" href="//unpkg.com/docsify/themes/dark.css">
  <link rel="stylesheet" href="//unpkg.com/docsify/themes/pure.css">
  <link rel="stylesheet" href="//unpkg.com/docsify/themes/dolphin.css">

插件

docsify的插件不算非常丰富,但是可以满足中小型项目的文档需求,你可以在这里找到Docsify的插件和配置方法,比较常用的有全文搜索和图片缩放。配置插件大多都比较简单,只需在index.html中引入一些js

部署

Docisfy支持部署到你的VPS,Github Pages,Gitlab Pages等服务。这里我们简单的介绍Github Pages是如何部署的,VPS的部署非常简单,只需要你的Nginx指向你的文档根目录即可

Github上新建repo或将文档放在已有repo下的docs目录下,在设置页面开启Github Pages并选择合适的位置,即可发布文档,如果你需要自定义域名,只需在文档根目录放置记录自定义域名的CNAME文件。

我的加速服务的技术文档就是由Docisfy生成的,有兴趣的可以来看看成品

Last modification:April 19th, 2019 at 10:55 pm
If you think my article is useful to you, please feel free to appreciate

Leave a Comment