blog/docs/写作指南.md

写作指南：在文章里插入图片 / 视频 / 音频

适用：content/posts/*.md（书评与技术轨通用）。资产目录约定 + 三种媒体的写法 + 体积纪律。

目录约定

content/posts/
├── my-post.md                    # 文章
└── assets/
    └── my-post/                  # 与文章 slug 同名：该篇私有资产
        ├── photo.jpg
        ├── clip.mp4
        └── voice.mp3

相对引用一律 ./assets/{slug}/文件名，构建时 Astro 图片服务自动出多尺寸 webp。

图片

标准 markdown 语法，alt 必填（无障碍 + 暗色降亮依据）：

![外滩夜景](./assets/my-post/bund.jpg)
*图：外滩的傍晚*            ← 紧跟媒体的斜体独立段 = 图注（居中小字）

• 图注可选；写法固定为 *…* 单独成段，紧跟图片
• 压缩纪律：入仓前长边 ≤2400px（可跑 python3 scripts/photos_ingest.py，对 posts 资产同样有效的思路，图片请自行用同规格压缩）

视频

markdown 原生不认视频，直接写 HTML 标签（Astro 透传）：

<video controls preload="metadata" src="./assets/my-post/clip.mp4"></video>
*片头三秒试拍*

• preload="metadata" 必写（不预拖流量，只取时长/首帧）
• 样式已全局处理（全宽圆角黑底）

音频

<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）