返回

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

2024-06-17 Docsify Docsify官网 文档站点 轻量 站点生成器 Docsify GitHub 181 0

什么是 Docsify?

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

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

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

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官方文档

您可能感兴趣:

阿里云 云服务器 99元1年 2核2G 3M固定带宽 续费与新购同价

DOVE 网络加速器免费试用

顶部