笔记层级规范

本网站按 四层结构 组织笔记：

主界面 (index.md)
  └─ 分页面 (如 C语言学习/index.md)
       └─ 章节 (如 02-变量/index.md)
            └─ 子页面 (如 02-1-定义变量.md)

一、层级定义

层级	说明	路径示例	页面特征
主界面	网站首页，列出所有分类	`/`	无页脚导航（自动隐藏），点击分类进入分页面
分页面	一个大的分类入口	`/C语言学习/`	底部有页脚导航，顶部有"回到主界面"链接
章节	分页面下的子分类	`/C语言学习/02-变量/`	底部有页脚导航，顶部有"回到分页面"链接
子页面	实际笔记内容	`/C语言学习/02-变量/02-1-定义变量/`	顶部有"回到章节"链接

特殊情况

如果某个分类下内容很少（如仅有 1 个页面），可以省略章节层，直接作为分页面的子页面：
如 序章 没有独立章节，直接挂在 C语言学习/ 下
空分类（如暂未写入内容的STM32单片机学习），只需一个分页面即可

二、导航文件 (mkdocs.yml) 写法

标准结构

nav:
- 🏰 光之国的秘密基地: index.md
- 分类名:
  - 分类名: 分类名/index.md          # ← 分页面
  - 直接子页面: 分类名/页面.md         # ← 可选：直接挂分页面下
  - 章节名:                           # ← 章节
    - 章节名: 分类名/目录/index.md    # ← 章节首页
    - 子页面1: 分类名/目录/文件.md    # ← 子页面
    - 子页面2: 分类名/目录/文件.md

实际示例（C语言学习）

- C语言学习:
  - C语言学习: C语言学习/index.md        # 分页面
  - 序章: C语言学习/01-序章.md           # 直接子页面（无章节）
  - 变量:                                 # 章节
    - 变量: C语言学习/02-变量/index.md   # 章节首页
    - 定义变量: C语言学习/02-变量/02-1-定义变量.md
    - 变量赋值和初始化: C语言学习/02-变量/02-2-变量赋值和初始化.md
    - 练习题: C语言学习/02-变量/02-9-练习题.md
  - 判断与循环:                           # 章节
    - 判断与循环: C语言学习/03-判断与循环/index.md
    - 做判断: C语言学习/03-判断与循环/03-1-做判断.md

关键规则

分页面必须有 index.md
每个章节必须在 nav 中引用其 index.md（使侧边栏的章节名称为可点击链接）
章节 index.md 的条目名必须与章节名一致（如 变量: C语言学习/02-变量/index.md）
子页面的 nav 缩进比章节名多 2 格空格
忽略没有内容的分类（如 STM32 暂无内容时直接写 STM32单片机学习: STM32单片机学习/index.md）

三、章节首页 (index.md) 写法

要求

顶部使用 H1 标注章节名
用表格或列表列出所有子页面，必须用可点击的 Markdown 链接

正确写法

# 变量

> 本章目录

| 小节 | 内容 |
|:----:|:----:|
| [2.1 定义变量](./02-1-定义变量/) | 变量声明、命名规则 |
| [2.2 变量赋值](./02-2-变量赋值和初始化/) | 赋值运算符 |

错误写法 ❌

| [[02-1-定义变量|2.1 定义变量]] | ... |

Obsidian 格式的 [[wiki链接]] MkDocs 不识别，必须用标准 [显示名](./路径/)

链接路径规则

章节 index.md → 子页面：./子页面文件名/
分页面 index.md → 章节：./章节目录名/
主界面 index.md → 分页面：./分类名/

四、底栏导航标签规则

底部的「上一页/下一页」由 nav-footer.js 自动判断：

判断条件	显示
当前页与上/下页在同一章节内	上一页 / 下一页
当前页与上/下页在不同章节	上一章 / 下一章
当前页无章节（直接挂分页面下）→ 有章节的页面	上一章 / 下一章
有章节的页面 → 无章节的页面	上一章 / 下一章
最后一页（无下一页）	回到主页
主界面	整个页脚隐藏

章节归属由侧边栏导航的 data-md-level 决定，chapterMap 自动构建。

五、添加新笔记的步骤

流程

确定层级：新笔记属于哪个分类？是否需要创建新章节？
创建文件和目录：
新章节 → 创建目录 + index.md
新子页面 → 在对应章节目录下创建 .md 文件
更新 mkdocs.yml：在对应分类的 nav 中添加条目
更新章节 index.md：如果属于已有章节，在表格中添加一行链接

重建部署：

ssh root@47.101.199.146 "cd /root/notes-site && mkdocs build && cp -r site/* /var/www/notes/ && chown -R www-data:www-data /var/www/notes/"

或执行 /root/rebuild-notes.sh

注意事项

章节名用中文（与分类一致）
子页面文件名用有意义的英文/拼音，避免乱码
.md 文件第一行必须是 # 页面标题
分页面的 index.md 必须有可点击的子页面链接

六、nginx 配置要点

网站根目录：/var/www/notes/
配置文件：/etc/nginx/sites-enabled/notes
try_files 用 $uri $uri/ /index.html;（不能用 $uri/index.html，会导致双斜杠 bug）

最后更新：2026-06-13