从零搭这个站

这篇记录项目是怎么组织的，以及以后每天写作要用到的三条命令。

目录结构

personal-site/
├── docs/
│   ├── index.md              首页（hero + features）
│   ├── about.md              关于页
│   ├── languages/            编程语言，一个子目录一组
│   │   ├── python/           index.md 是概览，其余 .md 是文章
│   │   └── cpp/
│   ├── tools/                工具框架，同上
│   │   ├── opencv/  pytorch/  tensorrt/  other/
│   ├── notes/                笔记，同上
│   │   └── site/  math/  classic/
│   ├── public/               静态资源，构建时原样拷到根路径
│   └── .vitepress/
│       ├── config.mts        全站配置：标题、社交链接、搜索
│       ├── sidebar.ts        目录扫描，生成侧边栏与导航下拉
│       └── social-icons.ts   Gitee 官方红图标
├── scripts/
│   └── make-icons.py         从原图生成 favicon 与 logo
├── package.json
└── .gitignore

docs/public/ 里的图标由 scripts/make-icons.py 生成，换图时改脚本顶部的 SRC 再跑一次：

python scripts/make-icons.py

文件	用途
favicon.ico	16/32/48/64 多尺寸，老浏览器与任务栏
favicon-32.png	现代浏览器标签页
apple-touch-icon.png	iOS 添加到主屏，180×180
favicon-192.png	Android / PWA
logo.png	导航栏与首页 hero 的头像

三条命令

npm run docs:dev       # 本地预览，改文件热更新
npm run docs:build     # 构建到 docs/.vitepress/dist
npm run docs:preview   # 用构建产物起一个本地服务，检查上线效果

docs:dev 默认监听 http://localhost:5173，端口被占用时终端会打印实际端口。

写一篇新文章

放进对应分组的目录就行，侧边栏会自动出现，不需要改任何配置：

docs/languages/python/装饰器.md
docs/notes/math/svd-推导.md

规则只有五条：

1. 正文写一个 # 标题（放在 frontmatter 下面即可），侧边栏条目名直接取它
2. 想固定顺序，在 frontmatter 里写 order: 1；不写则按文件名排序，index.md 永远排第一
3. 想加一个新分组，就建一个目录，组名写在该目录任一文章的 frontmatter 里：group: 显示名 + group_order: 序号
4. 目录里有 index.md 就会在组内多一条「概览」；删掉它，「概览」跟着消失，但组名必须改由其他文章声明，否则会退回目录名
5. 想让它成为首页「读笔记」的落点，在 frontmatter 里写 date: 2026-10-20

首页的「读笔记」按钮不是写死的链接。构建时挑出最新的一篇指过去，判断顺序是： frontmatter 的 date → 最后一次 git 提交时间 → 文件修改时间；一篇都找不到就退回 /notes/math/。 线上是浅克隆，git 历史和 mtime 都失去区分度，想让它每次都对，就给文章写 date。

运行中的 dev server 不会感知文件的增删：新文章、新分组、删掉 index.md，都要重启一次才会反映到侧边栏。构建（docs:build）每次都是全新扫描，不受影响。

原理：docs/.vitepress/sidebar.ts 在构建时扫目录，config.mts 只负责调用它； 首页按钮由 latest-note.ts 算出落点，再经 config.mts 的 transformPageData 写回 frontmatter。

文章内可以用 VitePress 的容器语法做提示块：

提示

::: tip / ::: warning / ::: danger / ::: details 都是内置的。

影响全站的几个开关

配置项	当前值	作用
cleanUrls	true	生成 /notes/site/hello 而不是 /notes/site/hello.html
lastUpdated	true	页脚显示「最后更新于」，依赖 git 提交时间
search.provider	local	本地全文搜索，构建时生成索引，不依赖第三方
base	默认 /	只有部署到子路径时才需要改

注意

lastUpdated 依赖 git 历史。如果这个目录还没 git init，页脚不会显示更新时间，把仓库初始化并提交一次就有了。