西瓜空间站

docsify 安装

12/28/2020 博客框架docsify

docsify

# 1. 什么是docsify

docsify一个神奇的文档网站生成器，可以快速帮你生成文档网站。不同于 GitBook、Hexo 的地方是它不会生成静态的 .html 文件，所有转换工作都是在运行时。如果你想要开始使用它，只需要创建一个 index.html 就可以开始编写文档并直接部署在 GitHub Pages (opens new window)。

文档地址：传送 (opens new window)

特性 (opens new window)

  • 无需构建，写完文档直接发布
  • 容易使用并且轻量 (压缩后 ~21kB)
  • 智能的全文搜索
  • 提供多套主题
  • 丰富的 API
  • 支持 Emoji
  • 兼容 IE11
  • 支持服务端渲染 SSR (示例 (opens new window))

# 2. 安装docsify

# 2.1 安装node.js

安装 docsify 需要用到npm包管理器，之前我们需要确保电脑已安装过 node.js，如果没安装，详见 node.js 安装 。

如果不确定电脑是否安装，输入以下命令，如果出现版本就说明已经安装过node.js 反之则未安装。

// 查看 node.js 版本
node -v
// 查看 npm 版本
npm -v
1
2
3
4

image-20230101203733527

# 2.2 安装docsify-cli工具

npm包管理器安装以后，需要安装docsify-cli 工具，推荐全局安装，可以方便地创建及在本地预览生成的文档。

// 推荐使用 sudo 提权安装，减少权限问题
sudo npm i docsify-cli -g
1
2

如果安装过程中出现权限问题，需要使用sudo提权安装

image-20230101204349315

提权安装后等待结束，可安装好

image-20230101204756045

# 3 初始化一个docsify 项目

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

docsify init ./docs
1

初始化成功后，可以看到 ./docs 目录下创建的几个文件

  • index.html 入口文件
  • README.md 会做为主页内容渲染
  • .nojekyll 用于阻止 GitHub Pages 忽略掉下划线开头的文件

可以直接编辑 docs/README.md 就能更新文档内容，也可以添加更多页面 (opens new window)。

如果不喜欢 npm 或者觉得安装工具太麻烦，可以直接手动初始化 (opens new window)。

# 4 本地启动docsify服务

通过命令运行 docsify serve 启动一个本地服务器，可以方便地实时预览效果。默认访问地址 http://localhost:3000 (opens new window) 。

// 启动当前目录下的 docs
docsify serve docs

// -p 指定端口，默认端口为3000  也可以使用绝对路径
docsify serve -p 8080 /Users/evan/Desktop/xiguaBlog/docs
1
2
3
4
5

启动成功如下如，可以使用浏览器访问对应地址，查看效果。

image-20230101210443195

默认初始化后的页面

image-20230101210805495

# 5. docsify常见说明

只选取部分常见功能说明，全部功能详见官方文档 (opens new window)。

# 5.1 目录和路由说明

假设你的目录结构如下：

.
└── docs
    ├── README.md
    ├── guide.md
    └── zh-cn
        ├── README.md
        └── guide.md
1
2
3
4
5
6
7

guide.md 文件，那么对应的路由就是/#/guide

访问的文件和对应的URL 如下：

docs/README.md        => http://domain.com
docs/guide.md         => http://domain.com/guide
docs/zh-cn/README.md  => http://domain.com/zh-cn/
docs/zh-cn/guide.md   => http://domain.com/zh-cn/guide
1
2
3
4

# 5.2 定制侧边栏

为了获得侧边栏，您需要创建自己的_sidebar.md，你也可以自定义加载的文件名。默认情况下侧边栏会通过 Markdown 文件自动生成，效果如当前的文档的侧边栏。

首先配置 loadSidebar 选项，具体配置规则见配置项#loadSidebar (opens new window)。

<!-- 在 index.html 文件修改 -->
<script>
  window.$docsify = {
    // 加载侧边栏文件
    loadSidebar: true
  }
</script>
1
2
3
4
5
6
7

接着创建 _sidebar.md 文件，内容如下

<!-- docs/_sidebar.md -->
* [首页](zh-cn/)
* [指南](zh-cn/guide)
1
2
3

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

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

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

<!-- 在 index.html 文件修改 -->
<script>
  window.$docsify = {
    loadSidebar: true,
    alias: {
      '/.*/_sidebar.md': '/_sidebar.md'
    }
  }
</script>
1
2
3
4
5
6
7
8
9

当层目录中的 README.md 文件会作为当层目录路由的默认网页。

# 5.3 定制顶部侧边栏

定制顶部栏和侧边栏逻辑类似，只是文件名称和参数名称不一致，详见官方文档。

# 5.4 栏目选中的条目作为页面的标题

一个页面的 title 标签是由侧边栏中选中条目的名称所生成的。为了更好的 SEO ，你可以在文件名后面指定页面标题。

<!-- docs/_sidebar.md -->
* [Home](/)
* [Guide](guide.md "The greatest guide in the world")
1
2
3

# 5.5 显示目录

自定义侧边栏同时也可以开启目录功能。设置 subMaxLevel 配置项，具体介绍见 配置项#subMaxLevel (opens new window)。

# 5.6 忽略副标题

当设置了 subMaxLevel 时，默认情况下每个标题都会自动添加到目录中。如果你想忽略特定的标题，可以给它添加 <!-- {docsify-ignore} --> 。

# Getting Started

## Header <!-- {docsify-ignore} -->

该标题不会出现在侧边栏的目录中。
1
2
3
4
5

要忽略特定页面上的所有标题，你可以在页面的第一个标题上使用 <!-- {docsify-ignore-all} --> 。

# Getting Started <!-- {docsify-ignore-all} -->

## Header

该标题不会出现在侧边栏的目录中。
1
2
3
4
5

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

# 6. docsify线上部署

当我们本地调试好docsify项目后，可以将他部署为线上项目，之后我们就可以通过浏览器访问我们的博客啦。 这里利用的是 github 提供的 Pages，免费部署，当我们把项目上传github 以后可以通过项目页面的Settings -> Pages 免费发布我们博客。