Docsify轻松写文档

技术

前不 久,我发过一篇用 VitePress 写文档的文章,但其还是有所局限性:

  • 需要依靠 VitePress 脚手架,如果使用生成的静态文件无法在 Vercel 中部署;
  • 如果使用 Vercel 的 Node 环境,GitHub 又不允许上传以 . 开头的文件/文件夹。

由此可见,VitePress 的局限性很大,在这种情况下,我们就需要寻找一个新的文档工具。

这种情况下,我发现了一个新的文件构建工具:Docsify。

Docsify特点、优缺点十分明显。

优点呢,Docsify 不会生成静态文件,管理简单。而缺点也是它,仅有的 HTML 也是采用 JS 加载,导致搜索引擎收录可能性极低。

首先,Docsify采用的是 HTML + JS + Markdown 的机制。不懂?来看看下面的一段。

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Mix-Space</title>
  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
  <meta name="description" content="Description">
  <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">
</head>
<body>
  <div id="app"></div>
  <script>
    window.$docsify = {
      name: 'Mix-Space',
      coverpage: true
    }
  </script>
  <!-- Docsify v4 -->
  <script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
</body>
</html>

看看,有没有看懂什么?

好吧,我也没看懂,让我们一行一行的来研究。

1 ~ 8 行直接跳过,那就是普通的 HTML 。

然后看看第 9 行。第九行是一个 link ,引入的是 Docsify 的主题 CSS。

然后 13 ~ 19 行是 Docsify 的全局配置,name 代表 文档的名称。

第 20 行是引入 Docsify 的 JS。

然后,新建 _coverpage.md ,可以这么填:

# Mix-Space

> 一个全新打造的开源个人空间

- Dev. by Innei
- Doc by Wibus
- 文档版本:V1.0

[Demo](https://innei.ren) [Get Started](#信息)

然后,新建 README.md ,就可以写自己的内容了啊。

新建一个 .nojekyll 文件,以让 GitHub 能识别以下划线开头的文件。

然后,你直接打开 index.html ,就能看见你的手册了。不需要构建,直接 HTML 。

文档

创建于 2021-07-25