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

news2024/11/27 5:36:00

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环境，具体步骤如下：

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

npm i docsify-cli -g

安装完成的效果如下：
在这里插入图片描述

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

docsify init ./docs

改命令会产生 docs 目录和三个文件
在这里插入图片描述

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

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

docsify serve docs

成功启动如下显示
在这里插入图片描述

在浏览器输入 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)

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

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

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

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

node -v

如果版本低于7.6.0，你需要更新Node.js。你可以从Node.js官网下载和安装最新版本。
安装完毕后，重新在终端中输入以下命令，确认Node.js是否已经更新：

node -v

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

npm uninstall -g docsify-cli
npm install -g docsify-cli

完成上述步骤后，你应该可以成功执行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 的处理。