日常维护手册。仓库的总体布局、一次 push 之后的构建链路、各模块职责，详见 架构.md。本文只讲怎么动。
写一篇新文章
在 docs/<分类>/ 下放一个 .md，或一个 <名字>/index.md（页面捆绑，便于同目录放图）。文件首行的 # 标题 会被 tools/sync-hexo.py 自动抓成文章标题，也可以手动在 front matter 里写 title:。
front matter 是可选的。sync-hexo.py 会按下面顺序补字段：
title—— 取首个#标题，没有就用文件名date—— 取该文件 git log 中最早的提交时间（tools/sync-hexo.py:46的git_date()）categories—— 取文件所在的一级目录名tags—— 由tools/add-tags.py从正文扫描关键词生成，本地npm run add-tags触发
提交即发布：
git add docs/<分类>/<文件>
git commit -m "..."
git pushCI 在 master 分支触发，全程 2-3 分钟。
加一个新分类
在 docs/<新分类>/_index.md 里写：
---
title: "分类中文名"
---
# 分类中文名目录下所有文章会自动带上 categories: ["分类中文名"]，hexo 会渲染 /blog/categories/分类中文名/ 索引页。
改专题页
docs/database/_index.md 只是分类映射。专题页正文来自 tools/templates/database.md，由 tools/sync-hexo.py 的 create_database_landing_page()（约 tools/sync-hexo.py:500）原样复制到 source/database/index.md。
直接改 tools/templates/database.md，编辑器有高亮，git diff 也好看。
改菜单、推荐位、副标题、打赏图、Gitalk
全在 _config.matery.yml。它是主题 _config.yml 的 overlay，覆盖即可生效，主题升级不会被冲掉。
首页推荐文章在 tools/sync-hexo.py 顶部 FEATURED_POSTS 字典里配，value 是排序权重（越大越靠前）。
改主题样式、加组件
主题本体在 themes/matery/。直接改 _config.yml 会被升级冲掉，所以改动都走 tools/patch-theme.py：按 section 编号找注入点，用 replace_in_file() 做小手术。CI 每次跑都执行一遍，保证幂等。
要新增组件或修改 EJS 模板，改完记得把改动一并提交——主题仓库是 submodule 形态本地缓存，但 themes/matery/ 整体进 git，patch 之后的状态就在仓库里。
站内链接怎么写
跨文章用相对路径，文件名跟 docs/ 里一致：
见 [Babelfish 限制](./babelfish ddl已知限制.md)。分类页：/blog/categories/<分类中文名>/
标签页：/blog/tags/<标签名>/
不要写绝对 permalink（/blog/2026/07/03/xxx/）。日期由 git 提交时间决定，重算之后会变。
图片
- 与文章同目录或子目录里放图，markdown 用相对路径引用
sync-hexo.py把所有图片复制到source/images/，并重写文章里的引用- 页面捆绑（
<名字>/index.md）和图片同目录是推荐的写法
常见问题
push 后多久能看到？ CI 跑完即生效，通常 2-3 分钟。
文章没出现在分类里？ 检查 docs/<分类>/_index.md 是否存在，文件必须放在一级子目录下。
评论显示「未找到相关的 Issues」？ CI 末尾的 node tools/init-gitalk-issues.js 会给每篇新文章预创建 issue。如果漏了，看 CI 日志。
本地预览？ npm install && npm run server，访问 http://localhost:4000/blog/。source/ 和 public/ 本地生成，不入 git。
怎么加一个 hexo 辅助函数？ 在 scripts/ 下新建 .js，hexo.extend.helper.register('xxx', fn)，EJS 里就能用 <%= xxx(arg) %>。要改渲染前的文章 HTML，用 hexo.extend.filter.register('before_post_render', fn)。
