「docsify」学习笔记

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

docsify是什么？

简单来说，docsify可以动态地将Markdown文件转换html文件。所谓动态，即所有转换工作都是在运行时进行。这也就意味着，你如果有需要搭建一个小型项目知识手册之类的网站时，使用docsify可以让你只需要一个index.html以及一大堆Markdown文件即可动态地生成很多html文件，让你更加方便地编辑Markdown文件，而不去操心html页面的排版问题，专注于内容的创作。

docsify官网首页的几句简单介绍就说出了它的全部优点：

Simple and lightweight
No statically built html files
Multiple themes

准备使用docsify把自己家的家谱曼氏家谱实现网络化，寒假有事情做了~?

快速开始

docsify需要Node.js环境，不知道Node.js的同学可以把它认为是一个无界面需要使用命令行操作的软件，而docsify需要在该软件中运行，因此在开始学习docsify之前，需要安装Node.js环境，安装十分简单，点击访问官网，然后按照提示下载你所使用的操作系统版本，安装一路回车即可。

安装完成后，打开CMD命令行窗口（windows平台），输入node即可运行Node.js，出现以下提示说明安装成功：

C:\Windows\System32>node
Welcome to Node.js v19.1.0.
Type ".help" for more information.
>

然后就是安装docsify，继续在CMD命令行窗口中输入：

npm i docsify-cli -g

出现以下提示说明安装成功：

安装成功后，我们可以开始初始化docsify项目了，首先切换到你想要创建项目的文件目录，例如桌面文件夹：

cd C:\Users\myxc\Desktop

切换到对应文件夹后，就可以开始初始化项目了，如果你想将项目文件放在docs子文件夹内，使用以下命令即可创建项目文件：

C:\Users\myxc\Desktop>docsify init ./docs

Initialization succeeded! Please run docsify serve ./docs

创建成功后，可以发现在桌面出现了一个docs文件夹，里面有三个文件，分别是README.md、index.html、.nojekyll（这个文件好像是上传GitHub什么什么用的，可以不用管）。

C:\Users\myxc\Desktop>tree /f
文件夹 PATH 列表
卷序列号为 09C1-B27D
C:.
├─docs
│      .nojekyll
│      index.html
│      README.md

创建项目成功后，输入以下命令即可启动doscify服务：

C:\Users\myxc\Desktop>docsify serve docs

Serving C:\Users\myxc\Desktop\docs now.
Listening at http://localhost:3000

这个时候根据提示，打开电脑浏览器，访问电脑本地端口http://localhost:3000即可打开创建项目的首页。

使用VS code打开项目文件夹，编辑README.md文件，写下：

# Headline

> An awesome project.

Hello, world.

然后再次访问项目首页，即可发现：

这个时候我们就会发现，其实README.md文件中的内容即是项目首页显示的内容，即在运行项目后，docsify将Markdown文档README.md动态地转换成了网站的index.html文件。

这一步我在本地Node.js环境中运行没有问题，但是上传到Nigix服务器中，一旦访问README.md就会解析不出来，很奇怪。我的解决方法是在设置里添加：

homepage: 'index.md', // 首页文件为index.md

这样的话就可以把index.md代替README.md解析为首页，完美解决。

多页文档

链接

链接可以让我们在网页之间进行跳转，如何在项目文件中添加链接？正如上文所说，docsify是把md文件动态地转换为html文件，那么我们只需要在md文件中插入链接不就会自动地在html中呈现出来了吗？

在README.md文件中写入新的一行：

[>>Guide](./guide.md)

然后在项目文件中新建一个guide.md文件，写入内容：

# This is guide.md

> 这里是guide.md文件

⬇️点击下面的链接即可跳转至首页

[<<Index](./README.md)

然后我们即可发现两个页面中都出现了可以进行跳转的链接。

具体网页链接与md文件的对应方式举例说明，如果文件夹md文件如下所示：

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

那么对应的访问链接就是：

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

侧边栏

侧边栏的设置必须先创建一个_sidebar.md文件，然后写入：

# _sidebar.md文件

<!-- docs/_sidebar.md -->

* [Home](/)
* [guide](guide.md)
* [summary](summary.md)

然后在index.html添加设置：

window.$docsify = {
    loadSidebar: true // 打开侧边栏设置
}

这个时候打开网页就会发现已经有了侧边栏：

如果文件命名不是_sidebar.md，那么需要更改loadSidebar参数设置，例如我的侧边栏命名为summary.md，那么就需要将上一步在index.html中的设置更改为：

window.$docsify = {
    loadSidebar: 'summary.md' // load from summary.md
}

即可将summary.md文件设置为侧边栏。

多级目录

在_sidebar.md文件中写下目录链接：

# _sidebar.md文件

<!-- docs/_sidebar.md -->

* [Home](/)
* [guide](./guide.md)
* [summary](./summary.md)
* [前端](./前端/)
* [后端](./后端//)

如何在侧边栏中显示md文件中的二级标题、三级标题？需要在设置中添加：

subMaxLevel: 2 // 在sidebar目录中显示二级标题

自定义导航栏

开启导航栏需要在设置中添加：

loadNavbar: true

然后按照侧边栏_sidebar.md文件的模式编写_navbar.md：

<!-- docs/_navbar.md -->

* [guide](./guide.md)
* [summary](./summary.md)
* [前端](./前端/)
    * [html](./前端/html/README.md "二级标题-02")
    * [css](./前端/css/)
    * [js](./前端/js/)
* [后端](./后端//)

首页

开启首页需要在设置中添加：

coverpage: true

然后按照编写_coverpage.md文件：

<!-- _coverpage.md -->

![logo](_media/icon.svg)

# docsify <small>3.5</small>

> A magical documentation site generator.

- Simple and lightweight
- No statically built html files
- Multiple themes

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

默认情况下，封面和文档是在同一页的，[Get Started](#docsify)链接直接写标题就行。如果需要把封面单独作为一个页面显示，需要在设置中添加：

onlyCover: true,

需要注意的是，把封面单独作为一个页面后，跳转链接需要写全，例如：[Get Started](./README.md)。

默认情况下，首页背景色为随机色，如果需要固定背景图片或者颜色，可以通过：

<!-- background image -->

![](_media/bg.png)

<!-- background color -->

![color](#f0f0f0)

进行设置。

主题

官方推出的四种主题，只需要在首页引入即可使用：

<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css" />
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/buble.css" />
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/dark.css" />
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/pure.css" />

footer

添加设置：

plugins: [
        function (hook) {
          var footer = [
            '<hr/>',
            '<footer>',
            '<span><a href="https://family.manyacan.com">曼氏家族</a> &copy;2023.</span>',
            '<span>Published by <a href="https://www.manyacan.com" target="_blank">曼亚灿</a>.</span>',
            '</footer>'
          ].join('');

          hook.afterEach(function (html) {
            return html + footer;
          });
        }
      ],

一些插件

字数统计

引入文件：

<script src="https://cdn.jsdelivr.net/npm/docsify-count@latest/dist/countable.min.js"></script>

设置：

count: {// 【插件】字数统计
        countable: true,
        position: 'top',
        margin: '10px',
        float: 'left',
        fontsize: '0.9em',
        color: 'rgb(90,90,90)',
        language: 'chinese',
        localization: {
          words: "",
          minute: ""
        },
        isExpected: true
      }

搜索

引入文件：

<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>

设置：

search: { // 【插件】搜索
        noData: {
          '/': '没有结果 :('
        },
        paths: 'auto',
        placeholder: {
          '/': '搜索'
        }
      },

夜间模式切换

引入文件：

<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify-dark-mode@latest/dist/style.min.css" />
<script src="//cdn.jsdelivr.net/npm/docsify-dark-mode@latest/dist/index.min.js"></script>

设置：

darkMode: { // 【插件】夜间模式
        dark: {
          background: "#1c2022",
          toggleBtnBg: "#34495e",
          textColor: "#b4b4b4"
        },
        light: {
          background: "white",
          toggleBtnBg: "var(--theme-color)",
          textColor: "var(--theme-color)"
        }
      }

最后更新时间

引入文件：

<script src="https://cdn.jsdelivr.net/npm/docsify-updated/src/time-updater.min.js"></script>

设置：

timeUpdater: {  // 【插件】最后更新时间
        text: ">最后更新时间: {docsify-updated}",
        formatUpdated: "{YYYY}/{MM}/{DD}",
        whereToPlace: "bottom",  // "top" or "bottom", default to "bottom"
      },

----- END -----

博客站点：亚灿网志（Yacan's Blog）
本文链接：https://blog.manyacan.com/archives/2011/
版权声明：本文章采用 知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议 。