# docsify

：一个 SSG 工具，用于制作静态网站。它与 gitbook 相似，但功能多一些。

官方文档 (opens new window)
采用 Vue 前端框架，显示美观的网页。
使用它时，无需安装 npm 插件，只需引入一个 java script 文件。
- 使用它时，不需要事先将 MarkDown 文件转换成 HTML 文件。当用户查看网页时，才会在浏览器中即时渲染成 HTML 。
- 因此不需要事先构建网站，但不利于 SEO 。
会显示文章目录。
- 目录可以折叠显示，不过只能以 MarkDown 文件为单位进行折叠。

# 用法示例

在网站根目录下创建一个 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="//cdn.jsdelivr.net/npm/docsify@4/themes/vue.css"
    />
  </head>
  <body>
    <div id="app"></div>
    <script>
      window.$docsify = {
        //...
      };
    </script>
    <script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
  </body>
</html>

再创建一个 README.md 文件，为该页面提供显示内容：
```
echo Hello > README.md
```
启动一个 Web 服务器：
```
python3 -m http.server 80
```

# 目录结构

以下是 docsify 网站的目录结构示例：

.
├─ docs           # 可以给该目录单独编写 sidebar.md、navbar.md ，否则使用上一级目录的
│  ├─ Chapter1    # 可以给该目录单独编写 sidebar.md、navbar.md ，否则使用上一级目录的
│  │  ├─ 1.md
│  │  └─ 2.md
│  └─ Chapter2
│     └─ 1.md
├─ index.html     # 网站的入口点
├─ navbar.md
└─ sidebar.md

index.html 所在目录是网站的根目录，**任何文件中使用的相对路径的 URL ，都必须从这里开始。**因为 docsify 网站是纯 SPA 网站，当前目录始终停留在网站根目录，不能移动。

# 配置

# 侧边栏

在 index.html 中加入配置：

window.$docsify = {
  loadSidebar: 'sidebar.md',  // 显示侧边栏目录
}

侧边栏中的目录结构由 URL 所在目录下的 sidebar.md 决定，如下：

# 目录

- [第一章](Chapter1/)         # 如果不指定.md 文件，则默认读取该目录下的 README.md
  - [第一节](Chapter1/1.md)
  - [第二节](Chapter1/2.md)
- 第二章                      # 可以不给链接，只显示名字
  - [第一节](Chapter2/1.md)

可以给各个目录分别创建 sidebar.md ，从而显示不同的侧边栏目录。
- 如果 URL 所在目录下没有 sidebar.md ，则使用上一层目录的。
- navbar.md 的用法同理。

# 导航栏

在 index.html 中加入配置：

<nav>
  <<a href="#/">Navbar</a>   # 在页面顶部显示导航栏
</nav>
<div id="app"></div>
<script>
  window.$docsify = {
    loadNavbar: 'navbar.md'    # 启用导航栏的下拉列表
  }
</script>

导航栏的下拉列表由 URL 所在目录下的 navbar.md 决定，如下：

- [第一章](Chapter1/)
  - [第一节](Chapter1/1.md)
  - [第二节](Chapter1/2.md)
- 第二章
  - [第一节](Chapter2/1.md)

# 封面

docsify 默认没有显示封面，需要在 index.html 中加入如下配置：

window.$docsify = {
  coverpage: 'coverpage.md'   // 显示首页的封面
  // coverpage: ['/', '/Chapter1/', '/Chapter2/']   // 给多个目录分别显示封面
}

coverpage.md 的内容必须遵守以下格式：

# docsify

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

[GitHub](https://github.com/docsifyjs/docsify/)   # 显示一个链接
[第一章](Chapter1/)

# 网页图标

在 index.html 的 head 部分导入网页图标：

<link rel="icon" href="static/img/logo.ico" type="image/x-icon"/>

# 其它配置

window.$docsify = {
  name: '',        // 侧边栏顶部显示的文档标题
  nameLink: '/',   // 文档标题指向的链接
  repo: '',        // 在页面右上角显示一个到 GitHub 的链接
  maxLevel: 3,     // 解析 MarkDown 文件时的最大目录层数
  subMaxLevel: 4,  // 侧边栏目录的最大层数
  auto2top: true,  // 切换显示的文档时，自动跳转到页面顶部
}

# 扩展功能

# 搜索框

添加如下配置，即可在侧边栏上方显示一个搜索框，可对所有页面进行全文搜索：

<script>
window.$docsify = {
  search: {
      paths: 'auto',
      placeholder: 'Search',
      noData: 'No Results!',
  }
}
</script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>

# 嵌入图片

![logo](https://docsify.js.org/_media/icon.svg ':size=50x100')
![logo](https://docsify.js.org/_media/icon.svg ':size=100')

# 嵌入文件

从 docsify 4.6 开始，在 Markdown 中引用链接时，加上 ':include' 即可嵌入目标文件。

支持的文件类型	文件扩展名
iframe	.html .htm
markdown	.markdown .md
audio	.mp3
video	.mp4 .ogg
code	other file extension

例：

[](example.md ':include :type=markdown')
[](https://www.baidu.com/index.html ':include :type=iframe width=100% height=400px')

# 代码高亮

导入 Prism (opens new window) 的 js 文件之后，即可实现 MarkDown 文档代码块语法高亮。例如以下是支持 bash、C 语言的语法高亮：

<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-c.min.js"></script>

# 分页按钮

在 index.html 中添加如下脚本，即可在每个页面的底部显示跳转到前一文件、后一文件的按钮：

<script src="//unpkg.com/docsify-pagination/dist/docsify-pagination.min.js"></script>

# 使用主题

https://jhildenbiddle.github.io/docsify-themeable/#/ (opens new window)