程序笔记

Docsify | 轻量级无静态构建文档站点生成器

2024-10-20 56

什么是 Docsify？

Docsify 可以即时生成你的文档网站。与 GitBook 不同，它不会生成静态 html 文件。相反，它会智能地加载和解析你的 Markdown 文件并将其显示为网站。要开始使用它，你需要做的就是创建一个 index.html 并将其部署在 GitHub Pages 上。

Docsify 官网地址：https://docsify.js.org/

Docsity GitHub地址：https://github.com/docsifyjs/docsify

Docsify 的功能

无需静态构建的 html 文件简洁轻量智能全文搜索插件多种主题实用的插件 API 支持表情符号兼容 IE11 支持服务器端渲染（示例）

Docsify 的使用方法

快速开始

使用npm install命令安装Docsify，建议全局安装 docsify-cli，这有助于本地初始化和预览网站。

npm i docsify-cli -g

初始化

如果要在 ./docs 子目录中写入文档，可以使用 init 命令。

docsify init ./docs

编写内容

init完成后，可以在./docs子目录中看到文件列表。

index.html作为入口文件 README.md作为首页 .nojekyll防止GitHub Pages忽略以下划线开头的文件

你可以轻松地在./docs/README.md中更新文档，当然你可以添加更多页面。

预览你的网站

使用 docsify serve 运行本地服务器。可以在浏览器中通过 http://localhost:3000 预览你的网站。

docsify serve docs

手动初始化

如果你不喜欢 npm 或者在安装该工具时遇到困难，你可以手动创建 index.html：

<!-- index.html -->

<!DOCTYPE html>
<html>
  <head>
    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
    <meta name="viewport" content="width=device-width,initial-scale=1" />
    <meta charset="UTF-8" />
    <link
      rel="stylesheet"
      href="//cdn.jsdelivr.net/npm/docsify@4/themes/vue.css"
    />
  </head>
  <body>
    <div id="app"></div>
    <script>
      window.$docsify = {
        //...
      };
    </script>
    <script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
  </body>
</html>

指定 docsify 版本

请注意，在下面的两个示例中，当发布新的 docsify 主要版本时（例如 v4.x.x => v5.x.x），docsify URL 都需要手动更新。定期检查 docsify 网站以查看是否发布了新的主要版本。

在 URL 中指定主要版本 (@4) 将允许你的网站自动接收非破坏性增强功能（即“次要”更新）和错误修复（即“补丁”更新）。这是加载 docsify 资源的推荐方式。

<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/themes/vue.css" />
<script src="//cdn.jsdelivr.net/npm/docsify@4"></script>

如果你希望将 docsify 锁定到特定版本，请在 URL 中的 @ 符号后指定完整版本。这是确保你的网站无论对 docsify 的未来版本进行何种更改都保持相同外观和行为的最安全方法。

<link
  rel="stylesheet"
  href="//cdn.jsdelivr.net/npm/docsify@4.11.4/themes/vue.css"
/>
<script src="//cdn.jsdelivr.net/npm/docsify@4.11.4"></script>

手动预览你的网站

如果你的系统上安装了 Python，你可以轻松地使用它来运行静态服务器来预览你的网站。

cd docs && python -m SimpleHTTPServer 3000

cd docs && python -m http.server 3000

加载对话框

如果你愿意，你可以在 docsify 开始呈现文档之前显示加载对话框：

<!-- index.html -->

<div id="app">Please wait...</div>

如果你改变了 el，则应该设置 data-app 属性：

<!-- index.html -->

<div data-app id="main">Please wait...</div>

<script>
  window.$docsify = {
    el: '#main',
  };
</script>

更多设置请参考 Docsify官方文档。

更新于：3个月前

赞一波！

文章评论

评论问答

雷达智富