Docsify 快速入门与配置指南

2026-01-16 10:20:34作者：蔡丛锟

1. 项目目录结构及介绍

典型的 docsify 项目目录可能如下：

├── 404.html       # 自定义404页面
├── assets         # 存放图片、CSS样式等静态资源
├── index.html     # 入口文件，用于初始化docsify
├── _coverpage.md  # 封面页配置
├── _navbar.md     # 导航栏配置
├── _sidebar.md    # 侧边栏配置
├── README.md      # 主页文档
└── ProjectDocs    # 具体的文档内容目录
   ├── Doc1.md
   ├── Doc2.md
   └── ...

404.html: 非常规页面的错误处理。
assets: 保存所有静态资源，如图片、CSS样式、JavaScript脚本等。
index.html: 初始化文档站点的核心文件，这里会加载docsify库和其他插件。
_coverpage.md: 封面页内容，会在站点加载时显示。
_navbar.md: 自定义顶部导航栏的菜单项。
_sidebar.md: 自动生成左侧侧边栏的导航树。
README.md: 网站首页的主要内容。
ProjectDocs: 包含具体文档内容的目录。

2. 项目的启动文件介绍

index.html 是启动文件，它负责引入 docsify.js 并配置一些基本选项。例如：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>我的文档</title>
  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/lib/themes/vue.css">
</head>
<body>
  <div id="app"></div>

  <script>
    window.$docsify = {
      // 加载封面页
      coverpage: true,
      // 自动加载侧边栏
      loadSidebar: true,
      // 自动加载导航栏
      loadNavbar: true,
      // 设置搜索功能
      search: {
        maxAge: 86400000,  // 搜索结果缓存时间
        path: 'search.json',  // 搜索数据文件
        placeholder: '请输入关键词',
      },
    }
  </script>
  
  <!-- 引入docsify核心库 -->
  <script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
  
  <!-- 插件导入，例如：搜索、代码复制等 -->
  <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>
  <script src="//cdn.jsdelivr.net/npm/docsify-copy-code/dist/docsify-copy-code.min.js"></script>

  <!-- 可选：自定义CSS和JS -->
  <link rel="stylesheet" href="path/to/custom.css">
  <script src="path/to/custom.js"></script>
</body>
</html>

在此文件中，window.$docsify 对象包含了所有docsify的配置项，包括加载封面、侧边栏、导航栏以及搜索功能的设置。

3. 项目的配置文件介绍

`_coverpage.md`

覆盖页面的内容，通常包含项目的Logo、名称和简介。例如：

# Docsify 使用指南
> 使用 Docsify 构建快速、轻量级的文档网站

[开始阅读](README.md)

`_navbar.md`

顶部导航栏的配置，列出要展示的链接。例如：

* [首页](/)
* [关于我](/about.md)
* [GitHub](https://github.com/yourusername)
* [社区](https://docsify.js.org/#/community)

`_sidebar.md`

侧边栏配置，用于生成文档目录结构。例如：

* [快速入门](/quickstart.md)
  * [安装](/quickstart/install.md)
  * [运行](/quickstart/run.md)
* [高级使用](/advanced.md)
  * [自定义主题](/advanced/customize.md)
  * [插件开发](/advanced/plugins.md)