Docsify零构建文档站完全指南：从快速搭建到企业级部署

Cosolar
196 阅读9分钟

在技术文档领域，选择一个合适的文档站点生成工具往往比写文档本身更让人头疼。GitBook 太重、Hexo 需要构建、Docusaurus 配置繁琐……如果你只想安安静静地写 Markdown，然后立刻看到一个漂亮的文档网站，Docsify 就是为你而生的。

Docsify 的核心理念极其简单：不生成静态 HTML，运行时渲染 Markdown。这意味着你写完 .md 文件，刷新浏览器就能看到效果——零构建、零等待、零污染。

本文将从零开始，带你完整掌握 Docsify 的安装配置、主题定制、插件生态、全文搜索、多语言支持、部署上线，直到企业级实践的全流程。无论你是个人开发者搭建项目文档，还是团队构建知识库，这篇指南都能帮你快速上手。

第一章 Docsify 核心概念与工作原理

1.1 运行时渲染：Docsify 的灵魂

传统文档工具（如 Hexo、VuePress、Hugo）的工作流是：

Docsify vs 传统静态生成工具工作流对比

Markdown文件 → 构建工具 → 生成静态HTML → 部署

Docsify 完全不同，它的工作流是：

Markdown文件 → 浏览器运行时加载并渲染 → 直接展示

核心区别在于：Docsify 不会将 .md 文件预编译成 .html。它只在浏览器端通过 JavaScript 动态加载 Markdown 文件，使用内置的 marked 解析器将其转换为 HTML，然后插入到页面中。

// Docsify 核心渲染流程（简化版）
const renderProcess = {
  loadMarkdown: async (path) => {
    const response = await fetch(path);
    return response.text();
  },
  compileToHTML: (markdown) => {
    return marked.parse(markdown);
  },
  updateDOM: (html) => {
    document.getElementById('app').innerHTML = html;
  }
};

1.2 三大核心优势

优势说明
零构建步骤无需 npm install、webpack 打包等复杂流程，写完即看
轻量级部署仅需托管一个 index.html 和若干 .md 文件，无需后端服务
Git 友好不会生成一堆 .html 文件污染 commit 记录

1.3 与主流文档工具对比

特性DocsifyGitBookVuePressDocusaurusHugo
构建方式运行时渲染静态生成静态生成静态生成静态生成
构建步骤无需要需要需要需要
包体积~18kB较大中等较大二进制
学习成本极低低中中中
插件生态丰富一般丰富丰富丰富
SSR 支持有限支持支持支持支持
适合场景轻量文档/知识库书籍/文档技术文档开源项目文档博客/文档

1.4 Docsify 的适用场景

  • ✅ 项目技术文档
  • ✅ 个人知识库 / Wiki
  • ✅ API 文档
  • ✅ 内部团队文档
  • ✅ 快速原型展示
  • ❌ 大型电商网站（需要 SSR/SEO）
  • ❌ 高并发公开站点（运行时渲染有性能开销）

第二章 快速上手：5分钟搭建文档站

2.1 环境准备

Docsify 的运行只需要两样东西：

  1. Node.js（推荐 v18+）：用于安装 docsify-cli 工具
  2. 一个文本编辑器：写 Markdown
# 安装 docsify-cli
npm i docsify-cli -g

# 验证安装
docsify --version

2.2 初始化项目

# 创建项目目录
mkdir my-docs && cd my-docs

# 初始化 Docsify 项目
docsify init .

# 查看生成的文件
ls -la

初始化后会生成三个核心文件：

my-docs/
├── index.html   # 入口文件，Docsify 核心配置
├── README.md    # 首页内容
└── .nojekyll    # 阻止 GitHub Pages 忽略下划线开头的文件

2.3 本地预览

# 启动本地开发服务器（默认 http://localhost:3000）
docsify serve .

# 指定端口
docsify serve . --port 4000

打开浏览器访问 http://localhost:3000，你就能看到文档站了！

2.4 最小化 index.html 解析

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>My Docs</title>
  <!-- Docsify 主题样式 -->
  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">
</head>
<body>
  <!-- Docsify 渲染容器 -->
  <div id="app">加载中...</div>
  <!-- Docsify 核心脚本 -->
  <script>
    window.$docsify = {
      name: 'My Docs',       // 站点名称
      repo: '',              // GitHub 仓库地址
      loadSidebar: true,     // 加载侧边栏
      subMaxLevel: 3,        // 侧边栏最大层级
    }
  </script>
  <script src="//cdn.jsdelivr.net/npm/docsify@4/lib/docsify.min.js"></script>
</body>
</html>

关键配置说明：

配置项作用默认值
name侧边栏顶部显示的站点名称无
repo右上角显示的 GitHub 图标链接无
loadSidebar是否加载 _sidebar.md 侧边栏false
subMaxLevel侧边栏自动生成的标题层级0

第三章 目录结构与导航

3.1 推荐的项目结构

Docsify 推荐项目目录结构

my-docs/
├── index.html              # 入口文件
├── README.md               # 首页
├── _sidebar.md             # 侧边栏配置
├── _navbar.md              # 导航栏配置
├── _coverpage.md           # 封面页
├── guide/                  # 指南章节
│   ├── README.md           # 指南首页
│   ├── getting-started.md  # 快速开始
│   ├── configuration.md    # 配置说明
│   └── deployment.md       # 部署指南
├── api/                    # API 文档章节
│   ├── README.md           # API 首页
│   ├── core.md             # 核心 API
│   └── plugins.md          # 插件 API
├── images/                 # 图片资源
│   └── logo.png
└── .nojekyll               # GitHub Pages 兼容

3.2 侧边栏配置

创建 _sidebar.md 文件：

- **入门指南**
  - [首页](/)
  - [快速开始](guide/getting-started.md)
  - [配置说明](guide/configuration.md)

- **API 文档**
  - [核心 API](api/core.md)
  - [插件 API](api/plugins.md)

- **进阶**
  - [部署指南](guide/deployment.md)
  - [自定义主题](custom-theme.md)

⚠️ 重要：loadSidebar 必须设置为 true，否则 _sidebar.md 不会被加载。

3.3 导航栏配置

创建 _navbar.md 文件：

- [首页](/)
- [指南](guide/)
- [API](api/)
- [GitHub](https://github.com/your-repo)

配置中需要添加：

window.$docsify = {
  loadNavbar: true,  // 加载导航栏
}

3.4 封面页配置

创建 _coverpage.md 文件：

![logo](images/logo.png)

# My Docs <small>v2.0</small>

> 一个神奇的文档站点生成器

- 零构建，写完即看
- 轻量级，仅 18kB
- 丰富的插件生态

[GitHub](https://github.com/your-repo)
[开始阅读](#指南)

配置中需要添加：

window.$docsify = {
  coverpage: true,  // 启用封面页
  onlyCover: true,  // 首页只显示封面（可选）
}

第四章 主题定制与样式美化

4.1 内置主题

Docsify 提供了 4 套内置主题，只需修改 index.html 中的 CSS 链接即可切换：

<!-- Vue 主题（默认，推荐） -->
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">

<!-- Buble 主题 -->
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/buble.css">

<!-- Dark 主题 -->
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/dark.css">

<!-- Pure 主题（极简风格） -->
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/pure.css">
主题风格适用场景
Vue清爽现代通用文档站
Buble简洁圆润轻量文档
Dark暗色护眼技术文档/开发者
Pure极简白色偏学术文档

4.2 自定义 CSS 样式

创建自定义样式文件 style.css，覆盖默认主题：

/* 修改主色调 */
:root {
  --theme-color: #2563EB;       /* 主色：蓝色 */
  --theme-color-dark: #1D4ED8;  /* 主色深色 */
}

/* 修改侧边栏样式 */
.sidebar {
  background-color: #f8fafc;
  border-right: 1px solid #e2e8f0;
}

.sidebar > h1 {
  font-size: 1.5rem;
  color: #1e293b;
}

/* 修改内容区域样式 */
.content {
  max-width: 900px;
  margin: 0 auto;
  padding: 2rem;
}

/* 代码块样式 */
.markdown-section pre {
  background-color: #1e293b;
  border-radius: 8px;
  padding: 1.5rem;
}

.markdown-section code {
  font-family: 'JetBrains Mono', 'Fira Code', monospace;
}

/* 表格样式 */
.markdown-section table {
  border-collapse: collapse;
  width: 100%;
  margin: 1.5rem 0;
}

.markdown-section th,
.markdown-section td {
  border: 1px solid #e2e8f0;
  padding: 0.75rem 1rem;
}

.markdown-section th {
  background-color: #f1f5f9;
  font-weight: 600;
}

在 index.html 中引入：

<link rel="stylesheet" href="style.css">

4.3 社区主题

除了内置主题，社区还提供了多种高质量主题：

<!-- docsify-themeable：最流行的主题框架 -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple.css">

<!-- docsify-darklight-theme：暗色/亮色切换 -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify-darklight-theme@0/dist/style.css">

暗色/亮色切换配置：

window.$docsify = {
  darklightTheme: {
    siteFont: 'Source Sans Pro, Helvetica Neue, Arial, sans-serif',
    codeFontFamily: 'Roboto Mono, Monaco, courier, monospace',
    bodyFontSize: '15px',
    dark: {
      background: '#1e293b',
      textColor: '#e2e8f0',
      codeTextColor: '#e2e8f0',
      codeBackgroundColor: '#0f172a',
    },
    light: {
      background: '#ffffff',
      textColor: '#1e293b',
      codeTextColor: '#1e293b',
      codeBackgroundColor: '#f8fafc',
    }
  }
}

第五章 插件生态与核心功能

5.1 全文搜索

Docsify 插件生态系统架构

全文搜索是 Docsify 最实用的内置功能之一，无需额外配置即可启用：

window.$docsify = {
  search: {
    maxAge: 86400000,        // 缓存时间（毫秒）
    paths: 'auto',           // 自动索引所有页面
    placeholder: '搜索文档',  // 搜索框占位文字
    noData: '没有找到结果',   // 无结果提示
    depth: 6,                // 搜索标题深度
    hideOtherSidebarContent: true,  // 搜索时隐藏其他侧边栏内容
  }
}

引入搜索插件：

<script src="//cdn.jsdelivr.net/npm/docsify@4/lib/plugins/search.min.js"></script>

自定义搜索范围：如果只想搜索特定目录：

window.$docsify = {
  search: {
    paths: ['/guide/', '/api/'],  // 只索引这两个目录
  }
}

5.2 代码高亮

Docsify 内置支持 Prism.js 代码高亮，默认支持 HTML、CSS、JavaScript、Python 等常见语言。要支持更多语言，需要额外引入 Prism 组件：

<!-- 支持 Go 语法高亮 -->
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-go.min.js"></script>

<!-- 支持 Rust 语法高亮 -->
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-rust.min.js"></script>

<!-- 支持 SQL 语法高亮 -->
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-sql.min.js"></script>

<!-- 支持 Shell/Bash 语法高亮 -->
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js"></script>

<!-- 支持 YAML 语法高亮 -->
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-yaml.min.js"></script>

<!-- 支持 TOML 语法高亮 -->
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-toml.min.js"></script>

代码行号显示：

window.$docsify = {
  formatUpdated: '{YYYY}-{MM}-{DD} {HH}:{mm}',
}

5.3 代码复制按钮

<script src="//cdn.jsdelivr.net/npm/docsify-copy-code@2/dist/docsify-copy-code.min.js"></script>

5.4 Emoji 支持

<script src="//cdn.jsdelivr.net/npm/docsify@4/lib/plugins/emoji.min.js"></script>

使用方式：在 Markdown 中直接写 Emoji 代码，如 :smile: → 😄

5.5 外部链接跳转

自动为外部链接添加 target="_blank" 属性：

<script src="//cdn.jsdelivr.net/npm/docsify@4/lib/plugins/external-script.min.js"></script>

5.6 分页导航

在文档底部添加"上一页/下一页"导航：

window.$docsify = {
  pagination: {
    previousText: '上一章节',
    nextText: '下一章节',
    crossChapter: true,
    crossChapterText: true,
  }
}

<script src="//cdn.jsdelivr.net/npm/docsify-pagination@2/dist/docsify-pagination.min.js"></script>

5.7 字数统计

window.$docsify = {
  count: {
    countable: true,
    fontsize: '0.9em',
    color: 'rgb(90,90,90)',
    language: 'chinese'
  }
}

<script src="//cdn.jsdelivr.net/npm/docsify-count@latest/dist/countable.min.js"></script>

5.8 评论系统（Giscus）

集成 GitHub Discussions 作为评论系统：

window.$docsify = {
  plugins: [
    function giscus(hook) {
      hook.afterEach(function(html) {
        return html + '<div id="giscus-container"></div>';
      });
      hook.doneEach(function() {
        const script = document.createElement('script');
        script.src = 'https://giscus.app/client.js';
        script.setAttribute('data-repo', 'your-username/your-repo');
        script.setAttribute('data-repo-id', 'your-repo-id');
        script.setAttribute('data-category', 'Announcements');
        script.setAttribute('data-category-id', 'your-category-id');
        script.setAttribute('data-mapping', 'pathname');
        script.setAttribute('data-theme', 'preferred_color_scheme');
        script.setAttribute('data-reactions-enabled', '1');
        script.setAttribute('data-emit-metadata', '0');
        script.setAttribute('data-input-position', 'top');
        script.setAttribute('data-lang', 'zh-CN');
        script.crossOrigin = 'anonymous';
        script.async = true;
        document.getElementById('giscus-container').appendChild(script);
      });
    }
  ]
}

第六章 多语言（i18n）支持

6.1 目录结构

Docsify 原生支持多语言文档，目录结构如下：

my-docs/
├── index.html
├── README.md              # 默认语言首页（中文）
├── _sidebar.md            # 默认语言侧边栏
├── guide/
│   └── getting-started.md
├── en/                    # 英文文档
│   ├── README.md
│   ├── _sidebar.md
│   └── guide/
│       └── getting-started.md
└── ja/                    # 日文文档
    ├── README.md
    ├── _sidebar.md
    └── guide/
        └── getting-started.md

6.2 配置

window.$docsify = {
  name: 'My Docs',
  // 多语言配置
  alias: {
    '/.*/_sidebar.md': '_sidebar.md',  // 所有语言共享侧边栏
  },
  // 语言切换
  auto2top: true,
}

在导航栏中添加语言切换链接（_navbar.md）：

- [中文](/)
- [English](/en/)
- [日本語](/ja/)

第七章 部署上线

Docsify 五种部署方式对比

7.1 GitHub Pages 部署（推荐）

GitHub Pages 是 Docsify 最自然的部署方式——因为 Docsify 本质上就是一个 index.html + Markdown 文件，直接推送到 GitHub 仓库即可。

方式一：直接推送

# 初始化 Git 仓库
git init
git add .
git commit -m "init: docsify docs"

# 推送到 GitHub
git remote add origin https://github.com/your-username/your-repo.git
git push -u origin main

然后在 GitHub 仓库的 Settings → Pages 中选择 main 分支即可。

方式二：GitHub Actions 自动部署

创建 .github/workflows/deploy.yml：

name: Deploy Docs

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Pages
        uses: actions/configure-pages@v4

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: '.'

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

7.2 Vercel 部署

# 安装 Vercel CLI
npm i vercel -g

# 部署
cd my-docs
vercel

# 生产环境部署
vercel --prod

Vercel 会自动识别静态站点，无需额外配置。

7.3 Netlify 部署

创建 netlify.toml：

[build]
  publish = "."

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

然后在 Netlify 控制台中连接 GitHub 仓库，设置构建命令为空（因为无需构建），发布目录为 .。

7.4 Docker 部署

FROM nginx:alpine

# 复制文档文件到 Nginx 目录
COPY . /usr/share/nginx/html/

# 自定义 Nginx 配置（处理路由）
RUN echo 'server { \
    listen 80; \
    server_name localhost; \
    root /usr/share/nginx/html; \
    index index.html; \
    location / { \
        try_files $uri $uri/ /index.html; \
    } \
}' > /etc/nginx/conf.d/default.conf

EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

# 构建镜像
docker build -t my-docs .

# 运行容器
docker run -d -p 8080:80 my-docs

7.5 Cloudflare Pages 部署

  1. 登录 Cloudflare Dashboard → Pages
  2. 连接 GitHub 仓库
  3. 构建命令留空
  4. 输出目录设为 .
  5. 部署完成

第八章 高级配置与技巧

8.1 运行时配置（$docsify）

window.$docsify 是 Docsify 的核心配置对象，支持 50+ 配置项。以下是最常用的配置：

window.$docsify = {
  // 基础配置
  name: 'My Docs',                    // 站点名称
  nameLink: '/',                      // 名称链接
  repo: 'user/repo',                  // GitHub 仓库

  // 导航配置
  loadSidebar: true,                  // 加载侧边栏
  loadNavbar: true,                   // 加载导航栏
  coverpage: true,                    // 启用封面页

  // 渲染配置
  el: '#app',                         // 挂载元素
  formatUpdated: '{YYYY}-{MM}-{DD}',  // 文档更新时间格式
  relativePath: false,                // 相对路径模式

  // 路由配置
  alias: {
    '/.*/_sidebar.md': '_sidebar.md', // 侧边栏别名
  },
  autoHeader: true,                   // 自动添加标题
  subMaxLevel: 3,                     // 侧边栏最大层级

  // 行为配置
  auto2top: true,                     // 路由切换时自动回到顶部
  homepage: 'README.md',              // 首页文件
  notFoundPage: true,                 // 自定义 404 页面
  topMargin: 60,                      // 内容顶部间距

  // 外观配置
  themeColor: '#2563EB',              // 主题色
  mergeNavbar: true,                  // 移动端合并导航栏

  // 搜索配置
  search: {
    maxAge: 86400000,
    paths: 'auto',
    placeholder: '搜索',
    noData: '无结果',
  },
}

8.2 自定义插件开发

Docsify 的插件系统基于生命周期钩子，提供了 5 个核心钩子：

// 自定义插件模板
function myPlugin(hook, vm) {
  // 钩子1：初始化之前
  hook.init(function() {
    console.log('Docsify 初始化之前');
  });

  // 钩子2：每次路由切换之前
  hook.beforeEach(function(markdown) {
    console.log('路由切换前，Markdown 内容：', markdown.substring(0, 50));
    return markdown; // 可以修改 Markdown 内容
  });

  // 钩子3：每次路由切换之后（HTML 已生成）
  hook.afterEach(function(html) {
    console.log('路由切换后，HTML 内容：', html.substring(0, 50));
    return html; // 可以修改 HTML 内容
  });

  // 钩子4：每次路由切换之后（DOM 已更新）
  hook.doneEach(function() {
    console.log('DOM 已更新');
  });

  // 钩子5：初始化完成
  hook.mounted(function() {
    console.log('Docsify 已挂载');
  });

  // 钩子6：准备完成
  hook.ready(function() {
    console.log('Docsify 完全就绪');
  });
}

// 注册插件
window.$docsify = {
  plugins: [myPlugin]
};

实战示例：自动添加"编辑此页"按钮

function editOnGitHub(hook, vm) {
  hook.afterEach(function(html) {
    const repo = 'https://github.com/user/repo/edit/main';
    const path = vm.route.file;
    if (path) {
      const editLink = `<p style="text-align: right; margin-top: 2rem;">
        <a href="${repo}${path}" target="_blank" style="color: #2563EB;">
          ✏️ 编辑此页
        </a>
      </p>`;
      return html + editLink;
    }
    return html;
  });
}

window.$docsify = {
  plugins: [editOnGitHub]
};

8.3 Markdown 扩展语法

Docsify 支持一些 Markdown 扩展语法：

1. 文档嵌入

<!-- 嵌入其他 Markdown 文件 -->
[嵌入的文档](some/document.md)

2. 重要提示容器

> [!NOTE]
> 这是一个提示信息

> [!TIP]
> 这是一个技巧提示

> [!WARNING]
> 这是一个警告信息

> [!IMPORTANT]
> 这是一个重要信息

3. 忽略标题链接

<!-- 在标题后添加 {docsify-ignore} 忽略该标题的锚点 -->
### 不需要锚点的标题 {docsify-ignore}

<!-- 忽略所有子标题 -->
### 标题 {:ignore}

8.4 服务端渲染（SSR）

Docsify 支持 SSR，用于 SEO 优化：

// server.js
const docsifyServerRenderer = require('docsify-server-renderer');
const config = {
  name: 'My Docs',
  repo: 'user/repo',
  // ... 其他配置
};

const renderer = new docsifyServerRenderer(config);

// 渲染指定路径
renderer.render('/guide/getting-started').then(html => {
  console.log(html);
});

第九章 企业级实践

9.1 Monorepo 多项目文档

在企业中，通常需要在一个文档站中管理多个项目的文档。推荐结构：

docs/
├── index.html
├── README.md
├── _sidebar.md
├── _navbar.md
├── project-a/
│   ├── README.md
│   ├── architecture.md
│   └── api.md
├── project-b/
│   ├── README.md
│   └── guide.md
└── shared/
    ├── coding-standards.md
    └── deployment-guide.md

侧边栏配置（_sidebar.md）：

- **项目 A**
  - [概述](project-a/)
  - [架构设计](project-a/architecture.md)
  - [API 文档](project-a/api.md)

- **项目 B**
  - [概述](project-b/)
  - [使用指南](project-b/guide.md)

- **共享文档**
  - [编码规范](shared/coding-standards.md)
  - [部署指南](shared/deployment-guide.md)

9.2 CI/CD 自动发布

结合 GitHub Actions，实现文档的自动发布和版本管理：

name: Publish Docs

on:
  push:
    branches: [main]
    paths: ['docs/**']  # 只在 docs 目录变更时触发

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Check broken links
        run: npx linkinator docs/ --recurse --skip '^(?!http://localhost)'

      - name: Lint Markdown
        run: npx markdownlint-cli docs/**/*.md

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs

9.3 访问控制

Docsify 本身没有访问控制功能，但可以通过以下方式实现：

方式一：Cloudflare Access

将文档站部署到 Cloudflare Pages，然后配置 Access 策略：

  1. Cloudflare Dashboard → Zero Trust → Access → Applications
  2. 添加应用，选择域名
  3. 配置访问策略（邮箱白名单、IP 白名单等）

方式二：Nginx Basic Auth

server {
    listen 80;
    server_name docs.example.com;
    root /var/www/docs;
    index index.html;

    auth_basic "Internal Docs";
    auth_basic_user_file /etc/nginx/.htpasswd;

    location / {
        try_files $uri $uri/ /index.html;
    }
}

方式三：OAuth2 Proxy

使用 OAuth2 Proxy 在文档站前加一层认证：

server {
    listen 80;
    server_name docs.example.com;

    location /oauth2/ {
        proxy_pass http://oauth2-proxy:4180;
    }

    location / {
        auth_request /oauth2/auth;
        error_page 401 = /oauth2/sign_in;
        proxy_pass http://docs:3000;
    }
}

9.4 性能优化

1. CDN 加速

将 Docsify 核心文件和主题 CSS 托管到 CDN：

<!-- 使用 jsDelivr CDN -->
<script src="//cdn.jsdelivr.net/npm/docsify@4/lib/docsify.min.js"></script>
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">

2. 预加载关键资源

<link rel="preload" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css" as="style">
<link rel="preload" href="//cdn.jsdelivr.net/npm/docsify@4/lib/docsify.min.js" as="script">

3. Gzip 压缩

在 Nginx 中启用 Gzip：

gzip on;
gzip_types text/plain text/css application/json application/javascript text/xml;
gzip_min_length 256;

4. 图片懒加载

function lazyLoadImages(hook) {
  hook.afterEach(function(html) {
    return html.replace(/<img src=/g, '<img loading="lazy" src=');
  });
}

window.$docsify = {
  plugins: [lazyLoadImages]
};

9.5 SEO 优化

Docsify 运行时渲染对 SEO 不友好，但可以通过以下方式改善：

1. 预渲染（Prerender）

使用 docsify-cli 的预渲染功能：

docsify generate .

2. 添加 meta 标签

<meta name="description" content="你的文档站描述">
<meta name="keywords" content="docsify, 文档, 教程">
<meta property="og:title" content="My Docs">
<meta property="og:description" content="你的文档站描述">
<meta property="og:type" content="website">

3. Sitemap 生成

使用插件自动生成 sitemap：

// build 脚本中生成 sitemap
const fs = require('fs');
const path = require('path');

function generateSitemap(dir, baseUrl) {
  let sitemap = '<?xml version="1.0" encoding="UTF-8"?>\n';
  sitemap += '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n';

  function walk(currentDir) {
    const files = fs.readdirSync(currentDir);
    for (const file of files) {
      const fullPath = path.join(currentDir, file);
      const stat = fs.statSync(fullPath);
      if (stat.isDirectory()) {
        walk(fullPath);
      } else if (file.endsWith('.md')) {
        const urlPath = fullPath
          .replace(dir, '')
          .replace(/\.md$/, '')
          .replace(/\\/g, '/');
        sitemap += `  <url><loc>${baseUrl}${urlPath}</loc></url>\n`;
      }
    }
  }

  walk(dir);
  sitemap += '</urlset>';
  return sitemap;
}

fs.writeFileSync('sitemap.xml', generateSitemap('.', 'https://docs.example.com'));

第十章 常见问题与排错

Q1: 侧边栏不显示？

检查清单：

  1. index.html 中是否设置了 loadSidebar: true
  2. _sidebar.md 文件是否存在于根目录
  3. _sidebar.md 中的链接路径是否正确

Q2: 页面 404？

原因：Docsify 使用前端路由，服务器需要将所有请求重定向到 index.html。

Nginx 配置：

location / {
    try_files $uri $uri/ /index.html;
}

Q3: GitHub Pages 下划线文件不显示？

原因：GitHub Pages 默认使用 Jekyll，会忽略下划线开头的文件。

解决：确保 .nojekyll 文件存在于根目录。

Q4: 搜索功能不工作？

检查清单：

  1. 是否引入了搜索插件脚本
  2. 是否在 window.$docsify 中配置了 search 选项
  3. Markdown 文件是否有标题（搜索依赖标题索引）

Q5: 代码高亮不生效？

检查清单：

  1. 是否引入了对应语言的 Prism 组件
  2. Markdown 代码块是否指定了语言（如 ```python）

Q6: 移动端侧边栏不显示？

解决：Docsify 在移动端会自动隐藏侧边栏，点击左上角按钮即可展开。如果按钮不显示，检查 mergeNavbar 配置。

总结

Docsify 用最简洁的架构——一个 index.html + 若干 Markdown 文件——实现了令人惊喜的文档站体验。它的核心价值在于：

  1. 零构建：写完 Markdown 刷新即看，开发体验极致流畅
  2. 轻量级：核心仅 18kB，加载速度快
  3. 插件丰富：搜索、代码复制、分页导航、评论系统等开箱即用
  4. 部署简单：推送到 GitHub 即可上线，支持多种托管平台
  5. 高度可定制：主题、样式、插件、钩子，灵活度极高

当然，Docsify 也有其局限性：运行时渲染对 SEO 不友好、不适合大型高并发站点、SSR 支持有限。但对于绝大多数项目文档、团队知识库和个人博客来说，Docsify 的"零构建"哲学是最务实的选择。

如果你正在寻找一个"写完就能看"的文档工具，Docsify 值得你一试。

avatar
文章
阅读
粉丝