【知识网站教程】Docsify 中文版详细教程
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：
# 我的文档> 一个轻量级的文档生成器。- 无需构建
- 支持 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.cssdark.csspure.css
自定义主题
<link rel="stylesheet" href="assets/css/my-theme.css">
十、部署
1. GitHub Pages
- 将
docs/文件夹推送到 GitHub - 在仓库设置中启用 GitHub Pages，选择
/docs目录 - 访问
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存在- 文件路径正确
十二、更多资源
- 官方文档（中文）：https://docsify.js.org/#/zh-cn/
- 官方插件市场：https://docsify.js.org/#/plugins
- GitHub 仓库：https://github.com/docsifyjs/docsify
如需我帮你生成一个完整的 Docsify 项目模板（含主题、插件、封面、侧边栏等），请告诉我你的项目名称，我可以一键生成。