Docsify Easy Start

官方文档

Docsify官方中文文档

配置环境

node.js

Node.js官方下载地址

docsify-cli

全局安装docsify-cli工具。

Bash

npm i docsify-cli -g

网络不佳的，可以使用淘宝npm镜像源。

Bash

npm config set registry https://registry.npmmirror.com/ # 全局配置淘宝npm镜像
npm i docsify-cli -g

快速开始

初始化项目

如果想在项目的 ./docs 目录里写文档，直接通过 init 初始化项目。

Bash

docsify init ./docs

本地预览

通过运行 docsify serve 启动一个本地服务器，可以方便地实时预览效果。

默认访问地址 http://localhost:3000 。

Bash

docsify serve docs

多页文档

路由

如果需要创建多个页面，或者需要多级路由的网站，在 docsify 里也能很容易的实现。

例如创建一个 guide.md 文件，那么对应的路由就是 /#/guide。

假设你的目录结构如下：

.
└── docs
    ├── README.md
    ├── guide.md
    └── zh-cn
        ├── README.md
        └── guide.md

那么对应的访问页面将是

docs/README.md        => http://localhost:3000/
docs/guide.md         => http://localhost:3000/guide
docs/zh-cn/README.md  => http://localhost:3000/zh-cn/
docs/zh-cn/guide.md   => http://localhost:3000/zh-cn/guide

侧边栏

你可能想要浏览到一个目录时，只显示这个目录自己的侧边栏，这可以通过在每个文件夹中添加一个 _sidebar.md 文件来实现。

_sidebar.md 的加载逻辑是从每层目录下获取文件，如果当前目录不存在该文件则回退到上一级目录。例如当前路径为 /zh-cn/more-pages 则从 /zh-cn/_sidebar.md 获取文件，如果不存在则从 /_sidebar.md 获取。

当然你也可以配置 alias 避免不必要的回退过程。

Markdown

- [首页](/)
- [指南](guide.md)

HTML

<script>
  window.$docsify = {
    loadSidebar: true,
    alias: {
      '/.*/_sidebar.md': '/_sidebar.md'
    }
  }
</script>

目录

自定义侧边栏同时也可以开启目录功能。设置 subMaxLevel 配置项，代码中的参数表示显示两层。

HTML

<script>
  window.$docsify = {
    loadSidebar: true,
    subMaxLevel: 2
  }
</script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>

当然你也可以通过添加 ``的方式来忽略副标题。

Markdown

# Getting Started

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

导航栏

虽然可以使用html创建一个导航栏，但是我认为markdown的形式更为易懂。

首先配置 loadNavbar，默认加载的文件为 _navbar.md。

Markdown

- [首页](/)
- [指南](guide.md)

HTML

<script>
  window.$docsify = {
    loadNavbar: true
  }
</script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>

封面

开启渲染封面功能后在文档根目录创建 _coverpage.md 文件。

Markdown

![logo](_media/icon.svg)

# docsify <small>3.5</small>

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

- 简单、轻便 (压缩后 ~21kB)
- 无需生成 html 文件
- 众多主题

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

HTML

<script>
  window.$docsify = {
    coverpage: true
  }
</script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>