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.mdindex.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)

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

首页
首页
guide.html
guide.html

具体网页链接与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"
      },