Docsify介绍—md文件直接生成网页的工具

Markdown是一种轻量级标记语言，它使用易读易写的纯文本格式，用于编写文档，如README，wiki，博客文章等。Markdown语言最初由约翰·格鲁伯（John Gruber）和亚伦·斯沃茨（Aaron Swartz）在2004年创建，并且得到了广泛的应用。Markdown以简洁的语法约定和易于阅读的格式，使得文档具有良好的可读性和可移植性，并且可以轻松地转换为HTML等其他格式。
Markdown创建的文件的后缀名是 .md , 在项目中经常使用 README.md 来对项目进行一些描述， 这样在GitHub 直接可以很容易的查看。在大多数的IDE中都提供了Markdown语言的编写和Preview 的效果。
比如Eclipse：

比如VS Code：

相对在IDE中， 在Web中Markdown显示的效果更为美观， 而且对于项目来说， 将md文件转换为Wed端浏览的网页对于文档的阅读和维护都比较有益， 于是有了Docsify 这样的工具。

Docsify 是什么

Docsify 是一个基于JavaScript的文档网站生成器，可以速轻松地搭建基于文本文档的静态网站。它没有预设的主题，所有的网站样式都由Markdown文件生成，可以自由定制。docsify的优点是简单易用，不需要复杂的配置，文档可以直接写在Markdown文件中，支持插件扩展和多语言支持。
Docsify 直接将 Markdown 文件解析成 HTML，并且无需预先构建，只需部署文档的 Markdown 文件即可。这使得 docsify 非常轻便，可以直接运行在 GitHub Pages 上。

Docsify 的主要特征

• 无需构建：只需要创建 markdown 文件，然后通过 docsify 初始化项目后即可预览你的网站。这意味着你在创建文档或添加新部分时无须等待编译过程。

• 自定义主题：Docsify 提供了一些内置的主题可以使用，并且你可以通过覆盖默认样式自定义主题。

• 多种插件：Docsify 提供了强大的插件API，这个比其他静态站点生成器更加具有弹性和易扩展性。

• 全文搜索：Docsify 的搜索插件可以为你的文档站点提供快速的全文搜索。

• 提供丰富的 API 和全局 CLI 工具：你可以通过编程方式控制 docsify，或者在任何地方使用 CLI 工具来管理你的文档网站。

• 适合有版本需求的文档：你可以为你的文档创建不同的版本，并且通过 dropdown menu（下拉菜单）方便的进行切换。

Docsify 的快速使用

Docsify 是基于Node.js 的， 所以需要先安装Node.js环境， 具体步骤如下：

1. 安装Node.js， 需要 7.6.0之上的版本， 这里安装的是目前最新的长期支持版本 node-v18.18.0
   下载地址： https://nodejs.org/dist/v18.18.0/node-v18.18.0-x64.msi
2. 全局安装 docsify
   在命令含输入：

npm i docsify-cli -g
1

安装完成的效果如下：

3. 初始化docsify项目
   创建一个项目的目录， 这里是 D:\devworkspace\nodejs\docsify，命名行切换到该目录下， 执行

docsify init ./docs
1

改命令会产生 docs 目录和三个文件

• index.html 入口文件
• README.md 主页面
• .nojekyll 阻止GitHub忽略下划线开头的文件

4. 本地预览网站，将在 3000 端口启动，你可以在浏览器中通过 localhost:3000 进行访问
   命令行输入：

docsify serve docs
1

成功启动如下显示

5. 在浏览器输入 http://localhost:3000/#/
   

问题解决之— node_modules\docsify-cli\node_modules\update-notifier\index.js:103

在使用 docsify 启动服务的时候， 有时候会遇到如下问题：

node_modules\docsify-cli\node_modules\update-notifier\index.js:103
        async fetchInfo() {
              ^^^^^^^^^

SyntaxError: Unexpected identifier
    at createScript (vm.js:56:10)
    at Object.runInThisContext (vm.js:97:10)
    at Module._compile (module.js:549:28)
1
2
3
4
5
6
7
8

遇到的这个错误是由于你在执行docsify命令的时候，Node.js版本太低，无法识别或执行fetchInfo()这个async函数。

async/await是Node.js 7.6.0以后的版本开始支持的特性。需要升级Node.js到最新的稳定版本（比如 Node.js 14 或者 16 版本）来解决该问题。

以下是升级Node.js的步骤：

1. 首先确认当前Node.js的版本，可以在终端中输入以下命令：

node -v
1

2. 如果版本低于7.6.0，你需要更新Node.js。你可以从Node.js官网下载和安装最新版本。

3. 安装完毕后，重新在终端中输入以下命令，确认Node.js是否已经更新：

node -v
1

4. 更新 Node.js 后，可能还需要重新安装 docsify-cli ，确保它在新版本的环境下运行：

npm uninstall -g docsify-cli
npm install -g docsify-cli
1
2

完成上述步骤后，你应该可以成功执行docsify命令了。

.nojekyll 文件的作用

.nojekyll 是一个用于 GitHub Pages 服务的特殊文件。当 GitHub Pages 看到你的仓库中有这个文件时，它就会跳过 Jekyll 构建过程。

Jekyll 是一个静态网站生成器，它是 GitHub Pages 的默认构建工具。在正常情况下，当你推送文件到 GitHub Pages 的仓库时，Jekyll 会自动对你的文件进行处理，包括解析 Markdown 文件，处理 Liquid 模板标签，等等。

然而，有时候你可能并不想使用 Jekyll 对你的网站进行构建。比如说，你的网站可能已经是静态的 HTML/CSS/JavaScript 文件，或者你使用其他的工具自己进行构建。在这些情况下，在你的仓库根目录添加一个名为 .nojekyll 的文件（无需任何内容）会告诉 GitHub Pages 跳过 Jekyll 构建。

此外，如果你的站点包含下划线（_）开头的文件或文件夹，那么默认情况下 Jekyll 会忽略它们。如果你有这样的文件需要被 GitHub Pages 发布，那么你需要添加 .nojekyll 文件来跳过 Jekyll 的处理。

Docsify的功能和应用场景

使用 Docsify 可以实现以下功能：

1. 构建技术文档：使用 Docsify 可以方便地构建技术文档，为用户提供高质量的技术文档。
2. 搭建博客：使用 Docsify 可以快速搭建一款简洁美观的个人博客。
3. 建立个人主页：使用 Docsify 可以建立一个个性化的个人主页，向他人展示自己的能力和成果。

Docsify的应用场景包括：

1. 文档管理：Docsify可以帮助团队更好地管理和共享文档，可以在文档中加入标签、注释等功能以便于搜索和整理。
2. 客户支持：Docsify可以用来管理客户支持文档，例如FAQ、教程、指南等，方便客户快速找到需要的信息。
3. 销售资料：销售人员可以使用Docsify来管理销售资料，例如销售演示文档、客户案例等。
4. 项目管理：Docsify可以用来组织项目文档、会议记录、进度报告等，方便团队协作和沟通。
5. 培训资料：Docsify可以用来做培训文档，例如培训材料、课程大纲、考试题目等。

总之，Docsify适用于任何需要管理和共享文档的场景，可以帮助团队更好地管理信息、提高工作效率和合作能力。

参考

• 官方站点：https://docsify.js.org

---

---