Docsify 中文版详细教程

一个神奇的文档站点生成器，无需构建，支持动态加载 Markdown 文件。

我将为你整理一份基于 Docsify 官方文档的中文版详细教程，内容涵盖安装、配置、主题、插件、部署等核心内容，采用 Markdown 格式，方便你直接使用或集成到你的项目中。

一、简介

Docsify 是一个轻量级的文档网站生成器，它不会生成静态 HTML 文件，而是动态加载和解析 Markdown 文件，适合快速搭建项目文档、博客或知识库。

特点

  • 无需构建，直接运行
  • 支持 Markdown 文件
  • 支持主题和插件
  • 支持全文搜索
  • 支持多语言
  • 支持 GitHub Pages / Gitee Pages 部署

二、快速开始

1. 安装 Docsify CLI

npm i docsify-cli -g

2. 初始化项目

docsify init ./docs

生成的目录结构如下：

docs/
├── index.html          # 入口文件
├── README.md           # 主页内容
└── .nojekyll           # 阻止 GitHub Pages 忽略下划线开头的文件

3. 本地预览

docsify serve docs

访问：http://localhost:3000

三、基础配置

1. 修改 index.html

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>我的文档</title>
  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
  <meta name="description" content="Description">
  <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/lib/themes/vue.css">
</head>
<body>
  <div id="app"></div>
  <script>
    window.$docsify = {
      name: '我的文档',
      repo: 'https://github.com/yourname/yourrepo',
      loadSidebar: true,
      loadNavbar: true,
      coverpage: true,
      onlyCover: false,
      auto2top: true,
      homepage: 'README.md',
      basePath: '',
      autoHeader: true,
      maxLevel: 4,
      subMaxLevel: 3,
      search: 'auto',
      plugins: []
    }
  </script>
  <script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
</body>
</html>

四、目录结构建议

docs/
├── README.md          # 主页
├── guide.md           # 使用指南
├── _sidebar.md        # 侧边栏
├── _navbar.md         # 顶部导航栏
├── _coverpage.md      # 封面页
└── assets/
    ├── css/
    └── img/

五、封面页（Coverpage）

创建 _coverpage.md：

![logo](_media/icon.svg)

# 我的文档

> 一个轻量级的文档生成器。

- 无需构建
- 支持 Markdown
- 支持主题和插件

[GitHub](https://github.com/yourname/yourrepo)
[开始阅读](/README)

在 index.html 中启用：

window.$docsify = {
  coverpage: true
}

六、侧边栏（Sidebar）

创建 _sidebar.md：

- 指南
  - [快速开始](/guide.md)
  - [安装](/install.md)
- 高级
  - [插件开发](/plugin.md)
  - [主题定制](/theme.md)

启用：

window.$docsify = {
  loadSidebar: true,
  subMaxLevel: 3
}

七、导航栏（Navbar）

创建 _navbar.md：

- 中文
  - [首页](/)
  - [指南](/guide.md)
- English
  - [Home](/en/)
  - [Guide](/en/guide.md)

启用：

window.$docsify = {
  loadNavbar: true
}

八、插件系统

1. 搜索插件

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

2. 代码复制插件

<script src="//cdn.jsdelivr.net/npm/docsify-copy-code"></script>

3. 分页插件

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

4. 评论插件（如 Gitalk）

<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/gitalk/dist/gitalk.css">
<script src="//cdn.jsdelivr.net/npm/gitalk/dist/gitalk.min.js"></script>
<script>
  const gitalk = new Gitalk({
    clientID: 'GitHub Application Client ID',
    clientSecret: 'GitHub Application Client Secret',
    repo: 'GitHub repo',
    owner: 'GitHub repo owner',
    admin: ['GitHub repo owner and collaborators'],
    id: location.pathname,
    distractionFreeMode: false
  })
  docsify.plugins.push(function(hook, vm) {
    hook.doneEach(function() {
      gitalk.render('#gitalk-container')
    })
  })
</script>

九、主题定制

官方主题

  • vue.css（默认）
  • buble.css
  • dark.css
  • pure.css

自定义主题

<link rel="stylesheet" href="assets/css/my-theme.css">

十、部署

1. GitHub Pages

  1. 将 docs/ 文件夹推送到 GitHub
  2. 在仓库设置中启用 GitHub Pages，选择 /docs 目录
  3. 访问 https://yourname.github.io/yourrepo

2. Gitee Pages

步骤类似，支持静态托管。

3. 本地服务器

docsify serve docs --port 4000

十一、常见问题

Q1: 页面刷新 404？

使用 history.pushState 路由时，GitHub Pages 不支持 SPA 路由。

解决方案：
使用 hash 模式（默认）或添加 404.html 文件。

Q2: 侧边栏不显示？

确保：

  • loadSidebar: true
  • _sidebar.md 存在
  • 文件路径正确

十二、更多资源

如需我帮你生成一个完整的 Docsify 项目模板（含主题、插件、封面、侧边栏等），请告诉我你的项目名称，我可以一键生成。

# python
Logo
火山引擎 ADG 社区

火山引擎开发者社区是火山引擎打造的AI技术生态平台，聚焦Agent与大模型开发，提供豆包系列模型（图像/视频/视觉）、智能分析与会话工具，并配套评测集、动手实验室及行业案例库。社区通过技术沙龙、挑战赛等活动促进开发者成长，新用户可领50万Tokens权益，助力构建智能应用。

更多推荐

Chess用户界面设计：Tailwind CSS样式系统和组件库

GitHub推荐项目精选中的ch/chess是一个类似chess.com的多人在线象棋平台，它采用现代化的前端技术栈构建，尤其在用户界面设计上通过Tailwind CSS样式系统和组件库实现了优雅且功能丰富的交互体验。本文将深入探讨该项目如何利用Tailwind CSS打造一致的设计语言和高效的组件系统，为象棋爱好者提供沉浸式的游戏界面。## 🎨 Tailwind CSS样式系统：构建统一视

avatar 火山引擎 ADG 社区

终极指南：GPT-Engineer如何通过AI自动发现代码问题并提升质量

GPT-Engineer是一款强大的AI驱动代码工具，它能帮助开发者自动检测潜在代码问题、优化代码质量，让编程效率提升3倍以上。无论是新手还是资深开发者，都能通过这款工具轻松发现代码中的隐藏缺陷，减少调试时间，释放更多精力在创造性工作上。## 一键发现代码问题：GPT-Engineer的AI审查魔力GPT-Engineer的核心能力在于其内置的智能代码分析系统。通过集成Python代码格式

avatar 火山引擎 ADG 社区

SatDump中的纠错编码技术：从RS码到Turbo码的完整实现指南

在卫星数据传输过程中，信号往往会受到各种干扰，导致数据错误。SatDump作为一款通用卫星数据处理软件，集成了多种先进的纠错编码技术，确保从卫星接收到的数据能够准确解码。本文将深入解析SatDump中从Reed-Solomon（RS）码到Turbo码的实现细节，帮助读者理解这些技术如何保障卫星通信的可靠性。## 为什么纠错编码对卫星数据至关重要？卫星与地面站之间的通信链路面临着空间辐射、大

avatar 火山引擎 ADG 社区