云图札记博文写作规范

这篇写法指南把所有规则列清楚，照着来就行。

文件命名

所有博文放在 src/content/blog/ 目录下，文件名即文章 URL 的 slug：

src/content/blog/your-post-name.md

规则很简单：

• 全小写英文字母
• 单词之间用短横线 - 连接
• 不要用中文、空格、下划线或特殊字符
• 长度控制在 60 字符以内

示例：

✅ adding-search-to-blog.md
✅ blog-performance-optimization.md
✅ css-variables-design-system.md
❌ 搜索功能.md
❌ My Blog Post.md
❌ blog_performance.md

Frontmatter

每篇文章开头必须有一段 YAML frontmatter，用 --- 包裹：

---
title: '文章标题'
description: '一两句话概括文章内容'
pubDate: 2026-06-10
planted: 2026-06-10
category: '技术'
tags: ['Astro', '性能优化']
growth: bloom
---

字段说明

字段	必填	说明
title	✅	文章标题，引号包裹；也是双向链接的匹配依据
description	✅	一两句话摘要，用于 SEO 和列表预览
pubDate	✅	发布日期，格式 YYYY-MM-DD
planted	❌	播种日期，格式同 pubDate；不填则默认等于 pubDate
category	❌	分类，不填默认为”技术分享”
tags	❌	标签数组，不填默认为空
updatedDate	❌	更新日期，修改已有文章时添加
heroImage	❌	封面图路径，建议使用 public/ 下的 WebP 图片
pinned	❌	是否置顶，默认 false
series	❌	系列文集名称
seriesOrder	❌	系列内排序编号
seriesId	❌	系列唯一 ID，用于侧边栏锚点跳转
growth	❌	生长状态：seed（种子）/ bud（发芽）/ bloom（绽放），默认 seed
aliases	❌	别名数组，与 `[[原标题

分类

目前用到的分类：

分类	用途
技术	编程、开发、技术实践
教程	手把手教学、指南
笔记	学习笔记、知识整理
思考	观点、方法论、杂谈
游戏	游戏相关
知识	知识管理、效率工具
随笔	随想、记录
产品	产品设计、交互体验

系列文集

同一主题多篇文章可以归为一个系列，方便读者按顺序阅读：

---
title: 'Astro 博客搭建指南'
series: '云图札记搭建指南'
seriesOrder: 1
seriesId: yuntuzhaji-guide
---

• series：系列名称，同一系列文章填相同值
• seriesOrder：数字越小越靠前，不填则按发布日期排列
• seriesId：系列唯一 ID，建议用 kebab-case，同一系列文章保持一致
• 侧边栏会自动生成系列导航，上一篇 / 下一篇

生长状态（数字园丁）

文章有三种生长状态，体现写作的成熟度：

状态	标识	含义
seed	🌱 种子	初稿或思路草稿，尚未完成
bud	🌿 发芽	已有基本内容，仍在持续完善
bloom	🌸 绽放	内容成熟定稿，结构完整

不填 growth 字段时默认为 seed。

手动指定示例：

growth: bloom  # 文章已完成定稿

也可以通过运行脚本自动分配：

node scripts/assign-growth.cjs

分配规则：首发超过 180 天 / 被置顶 / 属于系列 → bloom；其余按时间自动判断。

双向链接

在正文中用 [[文章标题]] 引用其他文章，被引用的文章左侧目录栏底部会出现「根系」板块，展示哪些文章引用了它：

这篇和[[Obsidian 使用指南]]有很多关联……

标题太长？用别名语法：

这篇和[[Obsidian 使用指南|Ob指南]]有很多关联……

格式为 [[原标题|显示别名]：

• 原标题：用于匹配目标文章（精确匹配 frontmatter title），也是反向链接的依据
• 显示别名：渲染后链接上显示的文字，可以比原标题短得多
• 不带 | 时，显示文字等于原标题

别名仅影响显示，不影响匹配。同理，同一篇文章也可以在 frontmatter 中声明多个 aliases，效果相同。

被引用的文章左侧目录栏底部的「根系」板块会自动出现当前文章。

示例：

你在写的文章	内容	渲染结果
my-post.md	这篇和[[Obsidian 使用指南]]有关联	链接文字 = “Obsidian 使用指南”
my-post.md	`这篇和[[Obsidian 使用指南	Ob指南]]有关联`
结果	根系	Obsidian 使用指南 左侧目录栏底部出现「my-post」

不确定某篇文章的 title 是什么？去首页点击那篇文章，看浏览器标签页标题就是。 如果原标题写错了（匹配不到文章），链接会显示为红色虚线下划线文字，不会跳转到任何页面。

图片规范

放置路径

• 文章配图建议放在 public/img/ 目录下
• 装备、产品等固定资产图片放在 public/gear/ 目录下

推荐格式

优先使用 WebP 格式，体积比 PNG/JPG 小 70~90%，画质损失小。

已有转换脚本，添加新图片后运行：

npm run img:convert

脚本会自动将 public/ 下的 PNG/JPG 转为同名 WebP，保留原文件。

引用方式

![图片描述](/img/your-image.webp)

注意：不要用 src/content/blog/images/ 目录，该目录不存在。

灯箱放大

文章内的图片点击后会打开灯箱视图，支持：

• 双指捏合缩放
• 拖动平移
• 关闭按钮 / 点击遮罩退出

不需要额外配置，Markdown 图片语法自动生效。

Markdown 写法

正文

直接写 Markdown，不需要特殊 HTML 结构。几个注意事项：

• 段落：空行分段，不要用 <br> 硬换行
• 标题：从 ## 开始，# 是文章标题（由 frontmatter 的 title 生成）
• 代码块：用三个反引号 + 语言标识

```javascript
const greeting = 'Hello, World!';
```

支持的语法

博客支持以下 GFM（GitHub Flavored Markdown）语法：

表格

| 方案 | 优点 | 缺点 |
|------|------|------|
| 方案A | 快速 | 贵 |
| 方案B | 便宜 | 慢 |

任务列表

- [x] 已完成的任务
- [ ] 未完成的任务

删除线

~~这段文字会被划掉~~

行内代码

用 `pnpm run build` 构建项目

图片

![图片描述](/img/example.webp)

链接

[链接文字](https://example.com)

支持的 Markdown 扩展语法

除了标准 Markdown，博客还支持以下扩展语法——详见 博客写作语法指南：

文本高亮 ==重点文字== — 黄色背景标记关键词汇，克制使用效果最佳。

Emoji 快捷 :emoji_name: — 比直接输入 Emoji 更好维护，如 :warning: → ⚠️、:bulb: → 💡。

Callout 容器 :::tip\n内容\n::: — 醒目的信息提示框，适合技巧提示、注意事项、核心结论。支持 tip / note / warning / bug / abstract / example / question / success 等类型。

脚注 [^1] + [^1]: 说明 — 参考文献和补充说明，不打断正文阅读流。

不建议写法

以下语法博客不会渲染，避免使用：

• $数学公式$（LaTeX，未启用）
• HTML 标签（除非确实必要）

写作风格

这是云图札记写作风格，不是硬性规则但建议遵守：

说人话。 写你真正做了什么、想了什么，不要写教科书式定义和原理。读者来看博客是看经验，不是看文档。

具体优先。 “我试了三种方案，A 太慢放弃了，B 报错了，用 C 解决” 比 “经过充分调研和对比分析，最终选定了最优方案” 有用得多。

不要升华。 写到一个事实就停。“这个方案解决了我问题，构建时间从 12 秒降到 3 秒” 就是好结尾。不要加”技术的本质是…”之类的总结。

少用否定平行。 “不是 X，而是 Y” 的句式偶尔用可以，连续三段都是这种写法就过了。直接说 Y 就行。

代码要能跑。 贴的代码片段最好是从实际项目中复制出来，不是随手写伪代码。如果代码太长，贴关键部分，注释说明省略了什么。

更新日志

不要什么内容都去更新 changelog.json。只有当涉及以下变更时才更新：

• 新增页面（about、archive、友链等）
• 主题或功能重构（导航调整、阅读偏好、评论汇总等）
• 显著的设计变更（字体、排版、配色等）

日常发表不需要动 changelog.json，commit message 写清楚即可。

发布流程

写完文章后：

1. 把 .md 文件放到 src/content/blog/ 目录
2. 如果有新图片，放到 public/img/ 目录下，运行 npm run img:convert 转为 WebP
3. （可选）设置 growth 状态，不填默认为 seed
4. （可选）设置 planted 日期，不填默认为 pubDate
5. 本地构建验证：node ./node_modules/.bin/astro build
6. 推送到 Git 仓库，自动部署
7. changelog.json 只在主题/功能变更时更新，发表文章不用动