Docsify本地环境&&初始化

  • A+
所属分类：系统文档

请注意，本文编写于 1704 天前，最后修改于 1663 天前，其中某些信息可能已经过时。

当你有了一个全新的项目，但是有着大量的帮助文档和技术细节时，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** 语法混用。
​

Docsify本地环境&&初始化

Snipaste_2019-04-19_22-53-13.png
?> _TODO_ 完善示例
​

Docsify本地环境&&初始化

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生成的，有兴趣的可以来看看成品

  • 我的微信
  • 这是我的微信扫一扫
  • weinxin
  • 我的微信公众号
  • 我的微信公众号扫一扫
  • weinxin