Astro Notebook搭建

苦于 MkDocs 原生主题过于简陋，虽然生成速度快，但在交互和美观度上已经无法满足现代审美。加之近期频繁使用 Tailwind CSS，因此决定将全部个人笔记本迁移至 Astro (使用 v6 架构) 配合 Tailwind CSS 的静态化框架。

一、 项目目录结构

本站采用清晰的组件化和基于文件的路由架构。整体结构组织如下：

PathTo/blog/
├── astro.config.mjs          # Astro 配置文件（整合 Markdown 处理器与 KaTeX 插件）
├── package.json              # 项目依赖与运行脚本
├── tailwind.config.js        # Tailwind CSS 布局配置文件
├── public/                   # 纯静态托管文件（Logo、Favicon 等）
│   └── head.png              # 默认站点徽标
└── src/                      # 开发源码
    ├── components/           # 页面 UI 组件
    │   ├── Navbar.astro      # 顶部导航栏（包含模糊检索 overlay 弹窗和热键逻辑）
    │   ├── Sidebar.astro     # 侧边栏折叠目录（支持高亮与父级自动展开）
    │   └── ThemeToggle.astro # 深色/浅色模式切换器
    ├── content/              # 内容库（Markdown/MDX）
    │   ├── blog/             # 博客文章目录
    │   └── docs/             # 笔记本分类目录
    ├── content.config.ts     # 数据集合 Schema 强校验配置文件
    ├── layouts/              # 基础页面模板
    │   └── Layout.astro      # 全局主模板（Katex 样式及防暗色闪烁脚本注入）
    ├── pages/                # 页面物理路由
    │   ├── index.astro       # 引导主页
    │   ├── blog.astro        # 博客列表首页
    │   ├── blog/             # 博客动态子路由
    │   └── docs/             # 文档库动态子路由
    └── styles/               # 主题样式
        └── global.css        # 全局 Tailwind 变量与 Glassmorphism 样式

二、 侧边栏与检索组件控制说明

1. 侧边栏的 order 权重重构 (Sidebar.astro)

在初始模板中，目录树按照“文件夹优先、文件居后”的逻辑排序，这导致文档概览的 index.md 永远排在最后。 为了解决这一问题，我们重构了 src/components/Sidebar.astro 的排序引擎，将 Frontmatter 的 order 权重置为最高优先级。这样，只需要为 index.md 设置 order: 1，它就能浮动到同级目录的最顶端。

2. 全站模糊检索 (⌘K Modal)

模糊搜索基于构建期通过 getCollection('docs') 生成的静态 JSON 索引表。在测试时，我们发现很多页面由于缺少 Frontmatter 属性在检索中显示为 "Untitled Document"。 我们对全站 11 篇笔记（包括所有的 CTF Lab 写照和 CSAPP 笔记）进行了 Frontmatter 补齐，使得检索结果具有极佳的可读性。

四、 后续开发与发布维护说明

日常的更新和发布流程极其简单：

1. 新建文档/博客：在 src/content/docs/ 或 src/content/blog/ 下直接建立 .md 文件，指定 title 和 order。
2. 预览开发服务：执行 npm run dev 即可进行本地预览。
3. 打包静态输出：执行 npm run build 打包。打包器会自动刷新全站模糊搜索的 JSON 索引表并静态优化文档中引用的本地插图。