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

  • 需要依靠 VitePress 脚手架，如果使用生成的静态文件无法在 Vercel 中部署；
  • 如果使用 Vercel 的 Node 环境，GitHub 又不允许上传以 . 开头的文件/文件夹。
  • 不知为何，当我尝试添加图片的时候，部署至服务器会导致 Vue Error

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

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

Docsify特点十分明显。

优点呢，Docsify 不会生成静态文件，管理简单，而且只需要一个html和一堆Markdown，不用Node。而缺点也依旧突出，仅有的 HTML 也是采用 JS 加载，导致搜索引擎收录可能性极低（话说咱写个手册又不是博客辣么在乎收录搞啥）。

首先，Docsify采用的是 HTML + JS + Markdown 的机制，其中，html担任的是类似配置文件的任务。

不懂？来看看下面的一段。

<!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">
 <!-- 也可以用其他的主题，例如 Dark 或者其他的，换上链接就 OK. -->
  <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 -->
  <!-- 也可以用别的版本，也可以下载docsify的js后用本地的文件 -->
  <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 ，可以这么填：

<!- Md内容为转载的某xx文档的cover ->
# Mix-Space

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

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

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

然后，新建 README.md （README.md是首页，而非index.md） ，就可以写自己的内容了啊。

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

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

Docsify 还有一个优点，就是可以markdown嵌套。

例如下面的文件路径：

--- root
------- docs
----------- | README.md
----------- | index.html
-----------   zh-cn
-------------- | README.md

这样的话，我们可以不在zh-cn中创建配置文件，只写手册的Markdown（正常的README），比类似的产品好得多（实则我懒）。