Docsify快速上手与进阶指南

前言介绍

Docsify 是一个基于JavaScript的文档网站生成器，可以速轻松地搭建基于文本文档的静态网站。 它没有预设的主题，所有的网站样式都由Markdown文件生成，可以自由定制。 docsify的优点是简单易用，不需要复杂的配置，文档可以直接写在Markdown文件中，支持插件扩展和多语言支持。

准备工作

1. 准备一台服务器
   这里推荐雨云，雨云是国内领先的具有自主知识产权的云计算平台，有云服务器、虚拟主机、游戏云、CDN、云电脑等产品，无论你是新手小白，还是云上大佬，都能给您优秀的体验。
   优惠码： yhj 👈（注册绑定微信享受5折优惠）

2. 本地电脑安装 npm

环境安装

全局安装 Docsify CLI

首先，推荐全局安装 docsify-cli 工具，它能极大地简化创建和本地预览文档的过程。

npm i docsify-cli -g

确保 docsify-cli 成功安装后，就可以开始初始化你的文档项目了。

初始化项目

创建文档目录

如果你想在项目的一个特定目录（例如 ./docs）中编写文档，可以使用 init 命令来初始化这个目录。

docsify init ./docs

• index.html：作为文档入口的HTML文件。
• README.md：默认的主页内容，直接编辑此文件即可更新主页。
• .nojekyll：一个空文件，用于告知GitHub Pages不要忽略下划线开头的文件。

三、撰写文档

直接在 docs/README.md 文件中开始撰写你的文档内容。此外，你也可以在 docs 目录下添加更多 .md 文件来扩展文档页面。

四、本地预览

为了实时查看文档的渲染效果，使用 docsify serve 命令启动一个本地服务器。

docsify serve docs

默认情况下，预览页面将在 http://localhost:3000 打开，任何对文档的修改都会自动刷新页面，便于即时查看效果。

五、进阶功能

Docsify提供了一系列高级配置和特性，允许用户深度定制文档站点，提升用户体验和功能性。以下是一些关键的进阶功能及其详细说明：

1. 自定义配置

• 基础配置：在 index.html 文件的 <script> 标签内，通过设置 window.$docsify 对象来定制Docsify的行为。例如，你可以设置网站标题、是否启用侧边栏、指定加载的CSS或JS文件等。

  <script>
    window.$docsify = {
      name: '我的文档', // 网站标题
      repo: '用户名/仓库名', // 显示GitHub仓库链接
      loadSidebar: true, // 是否加载侧边栏，默认为false
      themeColor: '#3eaf7c', // 自定义主题颜色
      executeScript: true, // 是否执行页面中的脚本，默认为false
    };
  </script>
  

• 路由配置：可以定义更复杂的路由规则，如指定某个路径对应的具体页面。

2. 侧边栏定制

• 创建一个名为 _sidebar.md 的文件于 docs 目录下，用以自定义侧边栏菜单结构。你可以使用Markdown语法来组织菜单项，包括嵌套列表来表示子菜单。

<!-- docs/_sidebar.md -->

* [首页](zh-cn/)
* [指南](zh-cn/guide)

还要配置一下配置 loadSidebar选项

<!-- index.html -->

<script>
window.$docsify = {
  loadSidebar: true
}
</script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>

3. 插件集成

• Docsify支持丰富的社区插件来扩展功能，例如：

  • 代码高亮：通过引入 prismjs 或 highlight.js 插件来实现。
  • 搜索：使用 docsify-plugin-search 插件添加全文搜索功能。
  • 图表支持：集成 docsify-chart 插件展示图表。
  • TOC：自动插入目录插件 docsify-toc。

  安装插件通常需要在 index.html 引入相关JS文件，并在 $docsify.plugins 配置项中声明使用。

4. 主题与样式调整

• 主题切换：Docsify支持多种内置主题，通过设置 theme 属性切换，如 theme: 'dark'。

• 自定义CSS：可以通过向 $docsify 添加 styles 属性来自定义样式，或者直接在页面头部链接自定义CSS文件。

  <link rel="stylesheet" href="path/to/my-style.css">
  

• 使用外部主题：许多开发者为Docsify创建了独立的主题包，你可以在GitHub等平台上寻找并按照其说明文档集成。

5. 多语言支持

• Docsify 支持多语言文档，通过配置 languages 选项，指定不同语言对应的目录路径。

6. 性能优化

• 懒加载：Docsify 默认采用懒加载模式加载Markdown文件，提升初始加载速度。
• 资源压缩：在生产环境中，确保使用像webpack这样的构建工具来压缩和优化静态资源。

六、项目部署上线

1. 准备一台VPS服务器，这里拿雨云服务器来演示，服务器需要安装宝塔面板，我这里已经安装好了
2. 创建一个网站，上传自己的本地项目，只需将服务器的访问根目录设定为 index.html 文件。