博客文章书写规范
📅 发表于 2026-09-26
TIP
给自己定的规矩，也是给未来的自己留的说明书。发新文章前扫一眼这篇，能少踩很多坑。
存放与命名
- 文章统一放在
docs/<分类目录>/下，现有分类：linuxnetworkpythonjavadatabasealgorithmothersffxiv - 文件名可以用中文，但不要带空格（曾因此导致链接无法识别，见 Windows Terminal 美化那篇的教训）
- 新增分类要动六处：建目录 +
category.md登记 + 分类index.md+config.mjs的CATS标签映射 +config.mjs的 sidebar + 首页index.md的 features 卡片
Frontmatter（必须）
每篇文章头部必须带日期，这是全站自动化功能的数据源：
yaml
---
date: 2026-09-26
---- 格式必须是
YYYY-MM-DD，月日补零（别写2026-9-26） - 修改旧文章时追加
updated: YYYY-MM-DD；与 date 相同时页头只会显示发表日，不用担心冗余 - 有了这两个字段，页头日期、时间线页、sitemap 的
<lastmod>全部自动生成，不用手动登记
标题与结构
- 正文第一行是
# 文章标题，这个标题会直接作为时间线页的显示名，起得完整一点 - 章节从
##开始（右侧大纲只识别 H2/H3），开头建议一两句话说明这篇解决什么问题 - 旧的
::: tip Date:/Updated: :::手写日期块已废弃，一律走 frontmatter
发布检查清单
新文章写完后，按顺序过一遍：
- frontmatter 有
date，格式补零 ✓ - 到对应分类
index.md登记链接和一句话标题 ✓ - 到
config.mjs的sidebar对应分组加一条（分类名用侧栏显示名，link 不带.md）✓ npm run docs:build通过，无死链报错 ✓
图片资源
- 图片统一放在仓库
docs/public/images/下，正文用/images/...绝对路径引用（例：/images/blog-pic/xxx.png） - 新增图片：把文件放进对应目录即可，不要用外链图床，避免图床跑路后图片失效
- 文件名不要带空格，用
-代替；引用前确认npm run docs:build无死链报错
自动生效、无需维护的部分
以下功能全部由 frontmatter 驱动，发文章时什么都不用改：
- 时间线页
/timeline：按date自动倒序分组 - 页头日期行：
📅 发表于 … · 更新于 … - 搜索：本地 MiniSearch 带中文 bigram 分词，新文章自动进索引
- sitemap：
<lastmod>取updated，没有则取date
提交习惯
- commit message 用中文一句话说明白，如
新增 XXX 文章并登记到 XX 分类 - 国外线路：push 到
main后由 GitHub Actions 自动构建并发布到 GitHub Pages - 国内线路：由腾讯云 EdgeOne Pages「导入 Git 仓库」接入本仓库并自动构建，无需在 workflow 里配置
- 两条线路都依赖仓库源码，所以 push 前务必本地
npm run docs:build验证过