博客写作与图片接入指南

这篇是写给自己的备忘，也方便后来的人照搬。覆盖从新建文章、设置封面到优化搜索排名的全流程。

一、文章写作规范

1.1 目录结构

文章存放在 src/content/posts/ 目录下，支持 .md 和 .mdx 两种格式。

1
src/content/posts/
2
├── hello-world.md              # 直接放在根目录
3
├── my-article/
4
│   ├── index.md                # 或者放在子目录，用 index.md
5
│   └── cover.jpg               # 文章专属图片可以放在同目录
6
└── ...

约定：文件名即 slug（URL 路径的一部分）。hello-world.md → /posts/hello-world/，my-article/index.md → /posts/my-article/。

1.2 Frontmatter 字段说明

每篇文章顶部必须有 YAML 格式的 frontmatter，用 --- 包裹。完整字段如下：

1
---
2
title: "文章标题" # 必填 — 显示在页面标题、卡片、搜索结果中
3
published: 2026-06-12 # 必填 — 发布日期，影响排序
4
updated: 2026-06-12 # 可选 — 最后更新日期
5
description: "一句话概括文章内容" # 重要 — 显示在卡片摘要和搜索结果中
6
image: "/assets/posts/my-cover.webp" # 可选 — 封面图 URL
7
tags: ["标签1", "标签2"] # 可选 — 标签数组，用于分类和检索
8
category: "技术" # 可选 — 主分类（一个文章只能属于一个分类）
9
draft: false # 可选 — true 则在生产环境不显示
10
pinned: false # 可选 — true 则置顶显示
11
---

字段详解：

1.3 标题层级与可检索性

文章正文内的标题层级直接影响搜索效果：

• # 一级标题 — 等于文章标题，不要在正文中重复使用
• ## 二级标题 — 文章的主要章节（H2）。Pagefind 会给 H2 内容更高权重
• ### 三级标题 — 子章节（H3），同样被索引
• #### 四级标题 — 细节标题，权重较低

可检索性最佳实践：

1. 标题要包含关键词 — 避免”介绍""总结”这类泛化标题；用”Pagefind 静态搜索原理”而非”搜索原理”
2. H2/H3 划分清晰 — 搜索引擎按段落分组，层级越分明，检索精度越高
3. 首段包含摘要 — 第一个段落会被 Pagefind 作为上下文提取
4. 代码块内的文字不会被索引 — 不要在代码块中藏关键信息

1.4 description — 搜索排名的命门

description 可能是一篇文章里最有性价比的字段。它同时出现在四个地方：

1. 文章卡片 — 首页和列表里的摘要文字
2. <meta name="description"> — 搜索引擎结果显示的那行灰字
3. Pagefind 搜索命中 — 结果里的 excerpt
4. Open Graph — 分享到社交平台时的描述

怎么写才算好：

1
# 差 — 泛得没信息量
2
description: "本文介绍了相关知识"
3

4
# 好 — 具体、含关键词、补充标题没说到的
5
description: "用 Pagefind 为 Astro 静态博客添加全文搜索，涵盖索引配置、搜索框集成和中文分词处理"

• 长度压在 50-160 字
• 塞 2-3 个核心关键词
• 别照抄标题，标题已经写在上面了，description 要补它没说的事

1.5 标签与分类

标签（tags） 和 分类（category） 的区别：

分类与归档页河流配色联动，建议从下面的固定列表里选：

标签可以自由发挥，但建议保持统一风格，别中英文混着来。

1.6 草稿与置顶

1
# 草稿 — dev 可见，构建时隐藏
2
draft: true
3

4
# 置顶 — 首页排在最前（多个置顶按日期倒序）
5
pinned: true

工作流建议：写文章时先设 draft: true，完成后改为 false 或直接删除该行。

1.7 Markdown 扩展语法一览

本博客在标准 Markdown 基础上支持以下扩展：

二、图片接入

2.1 封面图（cover image）

每篇文章可以设置一张封面图，通过 image frontmatter 字段指定：

1
image: "/assets/posts/my-article-cover.webp"

封面图会在以下位置显示：

1. 首页 / 文章列表 — 文章卡片上的缩略图（带 hover 放大效果）
2. 文章页顶部 — 标题下方的 banner 横幅（最大高度 420px）
3. 映像页（/gallery/） — 照片墙的卡片图片，带倾斜相框效果
4. Open Graph — 社交媒体分享时的预览图
5. JSON-LD 结构化数据 — 搜索引擎可提取

如果文章没有封面图：

• 文章卡片不显示图片区域
• 文章页顶部直接显示标题（无 banner）
• Open Graph 使用自动生成的 OG 图片（Satori 渲染）
• /gallery/ 页不会收录该文章

2.2 正文内嵌图片

在 Markdown 正文中插入图片使用标准语法：

1
![图片描述](/assets/posts/diagram.png)

alt 文字（图片描述）很重要——它会：

• 在图片加载失败时显示为替代文字
• 被 Pagefind 索引（图片附近的文字可被搜索）
• 被屏幕阅读器读取（无障碍访问）

不推荐直接使用外部图床 URL，原因：

• 外部链接可能失效，导致图片无法显示
• 拖慢页面加载速度
• 搜索引擎无法保证索引

2.3 图片存放位置

所有图片放在 public/ 目录下。推荐按以下结构组织：

1
public/
2
├── assets/
3
│   ├── wallpaper/           # 壁纸（桌面端 + 移动端 webp）
4
│   │   ├── 1.webp
5
│   │   └── 1-mobile.webp
6
│   ├── font/                # 字体文件
7
│   ├── music/               # 音乐播放器相关
8
│   │   ├── cover/           # 专辑封面
9
│   │   └── url/             # 音频文件
10
│   └── posts/               # ★ 文章图片推荐放这里
11
│       ├── hello-world/
12
│       │   ├── cover.webp          # 封面图
13
│       │   ├── diagram.png         # 正文配图
14
│       │   └── screenshot.webp
15
│       └── getting-started/
16
│           └── cover.webp
17
└── favicon.svg

路径引用规则：

public/ 目录的文件在构建时会被复制到网站根目录，所以引用路径从根 / 开始，不写成 /public/xxx。

操作建议：

1. 为每篇文章在 public/assets/posts/<slug>/ 下创建专属文件夹
2. 封面图命名为 cover.webp 或 cover.jpg
3. 正文配图按内容命名（如 architecture.png、result.webp）
4. 路径中的 slug 和文章文件名保持一致

2.4 图片格式与大小建议

格式选择：

• WebP — 首选，同等质量下体积最小（约 JPEG 的 60%）
• JPEG — 照片类图片，不透明
• PNG — 需要透明背景或精确像素时（如截图、图表）
• SVG — 图标、Logo、简单图形

转换工具推荐：

1
# 将 PNG/JPEG 转为 WebP（需要安装 ImageMagick 或 cwebp）
2
magick input.png -quality 85 output.webp       # ImageMagick
3
cwebp -q 85 input.png -o output.webp           # cwebp
4

5
# 调整图片尺寸
6
magick input.png -resize 1200x output.webp     # 宽度 1200px，高度自适应

2.5 图片宽度控制

本博客支持通过 alt 文字控制图片宽度和居中对齐（由 rehype-image-width 插件处理）：

1
# 固定宽度（像素）
2

3
![描述 w-400](/assets/posts/diagram.png)
4

5
# 百分比宽度
6

7
![描述 w-80%](/assets/posts/screenshot.png)
8

9
# 居中显示
10

11
![描述 center](/assets/posts/image.png)
12

13
# 组合使用（宽度 + 居中）
14

15
![描述 w-600 center](/assets/posts/diagram.png)
16
![描述 w-70% center](/assets/posts/screenshot.png)

渲染效果：

![描述 w-400 center](/assets/posts/diagram.png) 会渲染为：

1
<figure>
2
  <img src="/assets/posts/diagram.png" alt="描述" style="width: 400px; display: block; margin: 0 auto;" />
3
</figure>

提示：如果 alt 文字中包含 title 属性（如 ![描述](url "这是标题")），插件会将标题渲染为 <figcaption>。

2.6 图片灯箱

正文中的图片点击后会自动弹出灯箱（lightbox）查看大图：

• 打开 — 点击文章正文中的任意图片
• 关闭 — 点击背景、按 Esc 键、或点击关闭按钮
• 导航 — 灯箱打开时可用 ← → 方向键切换同一文章中所有图片
• 移动端 — 支持左右滑动切换

不需要任何额外配置，这是博客的全局功能。

三、检索原理

3.1 Pagefind 全文检索

本博客使用 Pagefind 作为静态全文搜索引擎。工作流程：

1
npm run build
2
    ↓
3
1. astro build  → 生成 dist/*.html 静态页面
4
    ↓
5
2. npx pagefind --site dist  → 扫描 HTML，建立搜索索引
6
    ↓
7
3. 索引文件写入 dist/pagefind/
8
    ↓
9
4. 部署到 GitHub Pages 后，浏览器端搜索（无需后端）

搜索入口：

• 导航栏搜索图标（放大镜）
• 快捷键 Ctrl+K
• /search/ 页面

3.2 什么会被索引，什么不会

Pagefind 扫描最终生成的 HTML，以下内容进入索引：

• 标题（<h1> ~ <h4>）
• 正文段落（<p>）
• 列表（<li>）
• 表格（<td>, <th>）
• 图片 alt 文字

以下内容被 pagefind.yml 明确排除：

• 代码块（<code>, <pre>）
• 导航、页脚（<nav>, <footer>）
• Mermaid 图表渲染产物
• 音乐播放器面板
• 搜索弹窗自身

对应的写作后果：

• 代码块里的变量名搜不到 → 正文里用自然语言提一遍
• Mermaid 图里的文字搜不到 → 关键结论别只写在图里
• 导航和页脚不参与检索 → 别把重要线索藏在页脚

3.3 SEO 与 Open Graph

每篇文章会自动生成以下 SEO 元数据：

封面图优先级：image frontmatter > 自动生成的 OG 图片 (/og/<slug>.png) > 无图片

如果一个文章设置了 image，则该图片同时用于文章卡片、文章页 banner、OG 分享图和 JSON-LD。

附录：发前检查清单

一键过一遍，不踩坑：

• title 含关键词，不是”随笔 01”这种
• published 日期格式 YYYY-MM-DD
• description 已填，50-160 字，含关键词
• tags 2-3 个，风格统一
• category 从固定列表里选
• 正文 H2/H3 层次分明，标题有实词
• 正文第一段是摘要感（Pagefind 会抓它当上下文）
• 封面图放在 public/assets/posts_picture/
• image 路径对，没写成 /public/...
• 图片压缩过（WebP 优先，< 150KB）
• 图片都有 alt 描述
• draft: true 删了或改了
• npm run dev 预览正常
• npm run build 通过