From dcc20e9fb3fa434729a195ae407e66f23b7dfe58 Mon Sep 17 00:00:00 2001
From: wait4xx <X@alumni.nudt.edu.cn>
Date: Sun, 25 Oct 2026 11:45:39 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E5=86=99=E4=BD=9C=E6=8C=87=E5=8D=97?=
 =?UTF-8?q?=E2=80=94=E2=80=94=E4=B8=89=E5=AA=92=E6=8F=92=E5=85=A5=E8=AF=AD?=
 =?UTF-8?q?=E6=B3=95=E4=B8=8E=E4=BD=93=E7=A7=AF=E7=BA=AA=E5=BE=8B=EF=BC=88?=
 =?UTF-8?q?T5=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Spec: 2026-10-25_add-media-and-polish

Co-authored-by: GLM-5.3
---
 docs/写作指南.md | 67 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)
 create mode 100644 docs/写作指南.md

diff --git a/docs/写作指南.md b/docs/写作指南.md
new file mode 100644
index 0000000..aadfaea
--- /dev/null
+++ b/docs/写作指南.md
@@ -0,0 +1,67 @@
+# 写作指南：在文章里插入图片 / 视频 / 音频
+
+> 适用：`content/posts/*.md`（书评与技术轨通用）。资产目录约定 + 三种媒体的写法 + 体积纪律。
+
+## 目录约定
+
+```
+content/posts/
+├── my-post.md                    # 文章
+└── assets/
+    └── my-post/                  # 与文章 slug 同名：该篇私有资产
+        ├── photo.jpg
+        ├── clip.mp4
+        └── voice.mp3
+```
+
+相对引用一律 `./assets/{slug}/文件名`，构建时 Astro 图片服务自动出多尺寸 webp。
+
+## 图片
+
+标准 markdown 语法，alt 必填（无障碍 + 暗色降亮依据）：
+
+```markdown
+![外滩夜景](./assets/my-post/bund.jpg)
+*图：外滩的傍晚*            ← 紧跟媒体的斜体独立段 = 图注（居中小字）
+```
+
+- 图注可选；写法固定为 `*…*` 单独成段，紧跟图片
+- 压缩纪律：入仓前长边 ≤2400px（可跑 `python3 scripts/photos_ingest.py`，对 posts 资产同样有效的思路，图片请自行用同规格压缩）
+
+## 视频
+
+markdown 原生不认视频，直接写 HTML 标签（Astro 透传）：
+
+```html
+<video controls preload="metadata" src="./assets/my-post/clip.mp4"></video>
+*片头三秒试拍*
+```
+
+- `preload="metadata"` 必写（不预拖流量，只取时长/首帧）
+- 样式已全局处理（全宽圆角黑底）
+
+## 音频
+
+```html
+<audio controls preload="metadata" src="./assets/my-post/voice.mp3"></audio>
+*朗读：面纱选段*
+```
+
+## 体积纪律（git 仓红线）
+
+| 媒体 | 入仓上限 | 超限怎么办 |
+|---|---|---|
+| 图片 | 单张 ≤1MB（2400px 压缩后通常 200-800KB） | 重压 |
+| 音频 | ≤5MB（3 分钟 128kbps ≈ 2.8MB） | 降码率 |
+| 视频 | ≤5MB | 放仓外 `~/docker_apps/blog/media/`（photos-originals 同模式），文章里用绝对路径 `/media/xxx.mp4`；build.sh 同步段待该场景首次出现时补 |
+
+> 历史教训：21 张原图 196M 直接入仓曾撞死推送通道（git 历史 7a2880b 重写才甩掉）。
+
+## 三媒齐用的样例
+
+见 `content/posts/media-sample.md`（draft 文章，仅构建验证用，不上线）。
+
+## 发布提醒
+
+- push main → webhook 自动构建发布（约 10 秒）
+- 新文章要英文版：跑 `python3 scripts/translate/translate_posts.py`（幂等，代码块不会被翻译破坏的风险见其 README 注释；锁定润色用 frontmatter `locked: true`）