📒 笔记文档使用指南

这是什么

这是一个基于 mdBook 构建的静态笔记站点。所有笔记以 Markdown 格式保存在 Git 仓库中，通过 mdBook 生成漂亮的静态 HTML 页面。

🤖 给 AI 机器人（QQ 机器人）的操作说明

一键更新笔记

/usr/share/nginx/html/blog/update.sh

这个脚本会自动执行：

1. git pull — 从 Gitee 拉取最新笔记
2. 编译 s.c — 生成侧边栏文件 SUMMARY.md
3. mdbook build — 构建静态站点

服务器文件结构

/usr/share/nginx/html/
├── blog/                  ← mdBook 项目根目录
│   ├── book/              ← 构建输出 HTML（nginx 指向这里）
│   │   ├── index.html     ← 首页
│   │   ├── notes/         ← 生成的笔记页面
│   │   ├── css/           ← 样式文件
│   │   ├── FontAwesome/   ← 图标字体（本地化）
│   │   └── searchindex.js ← 全文搜索索引
│   ├── src/
│   │   ├── notes/         ← Markdown 笔记源文件（Gitee 仓库）
│   │   └── SUMMARY.md     ← 侧边栏目录（由 s.c 自动生成）
│   ├── theme/
│   │   ├── custom.css     ← 自定义样式
│   │   └── custom.js      ← 侧边栏折叠功能
│   ├── s.c                ← 侧边栏生成器源代码（C语言）
│   ├── s                  ← 编译后的二进制
│   ├── book.toml          ← mdBook 配置文件
│   └── update.sh          ← 一键更新脚本
└── blog.backup/           ← 备份

Nginx 配置

• 根目录: /usr/share/nginx/html/blog/book
• 域名: www.openso.top
• 反向代理路径: /sc, /test/, /shuiChan, /mqtt

📝 给人类用户的说明

浏览笔记

• 侧边栏: 左侧显示目录结构，点击 📁 文件夹标题展开/收起，点击 📄 文件标题查看内容
• 搜索: 点击顶部搜索图标 🔍 或按 s 键，可全文搜索
• 主题切换: 点击顶部 🖌️ 图标，可选择 Light / Rust / Coal / Navy / Ayu 五种风格
• 侧边栏开关: 点击 ☰ 图标可收起/展开侧边栏

笔记格式

所有笔记使用 Markdown 编写，支持：

• 标题（# ~ ######）
• 代码块（```）
• 表格、列表、引用
• 图片（![]()）
• 链接（[]()）

关于 mdBook

mdBook 是一个由 Rust 编写的静态站点生成器，专门用于创建文档/笔记网站。

特点：

• 纯静态 HTML，无需后端服务
• 内置全文搜索
• 支持多主题切换
• 响应式设计，支持手机端
• 侧边栏自动从目录结构生成

配置文件: blog/book.toml

[book]
title = "📒 笔记文档"
src = "src"

[output.html]
default-theme = "ayu"
print-enable = false
prev-next-buttons = false

侧边栏生成器（s.c）

s.c 是一个用 C 语言编写的工具，用于从笔记目录结构自动生成 SUMMARY.md（mdBook 使用的侧边栏定义文件）。

功能：

• 深度优先遍历目录，正确维护父子层级
• 目录优先于文件排序，各自按字母序
• 自动生成 README.md 作为目录的入口页
• URL 中的空格自动编码为 %20
• 无 .md 文件的目录自动跳过（不会出现在侧边栏）

最后更新: 2026-05-27