wait4xandGLM-5.3
71a799bd97
- 首页/归档/RSS（zh+en）集合查询统一 draft+hidden 双过滤——样张
永久保留为可访问不列出的活样例（回归测试资产）
- 写作指南视音频段更正：raw HTML 相对路径不走资产管线（实测），
媒体放 public/media/{slug}/ 用绝对 /media/ 引用，与仓外 store
同命名空间
验证: pnpm astro build exit 0（hidden 过滤后样张退出列表与 RSS）
Spec: 2026-10-25_add-media-and-polish
Co-authored-by: GLM-5.3
71 lines
2.7 KiB
Markdown
71 lines
2.7 KiB
Markdown
# 写作指南：在文章里插入图片 / 视频 / 音频
|
||
|
||
> 适用：`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
|
||
|
||
*图：外滩的傍晚* ← 紧跟媒体的斜体独立段 = 图注（居中小字）
|
||
```
|
||
|
||
- 图注可选；写法固定为 `*…*` 单独成段，紧跟图片
|
||
- 压缩纪律：入仓前长边 ≤2400px（可跑 `python3 scripts/photos_ingest.py`，对 posts 资产同样有效的思路，图片请自行用同规格压缩）
|
||
|
||
## 视频 / 音频
|
||
|
||
markdown 原生不认视音频，写 HTML 标签；**raw HTML 的相对路径不走 Astro
|
||
资产管线**（只有 `![]()` 图片语法走），所以媒体文件放 **`public/media/{slug}/`**
|
||
（构建原样拷入 dist），引用用绝对路径 `/media/...`：
|
||
|
||
```
|
||
public/media/my-post/clip.mp4 ← 文件放这里
|
||
```
|
||
|
||
```html
|
||
<video controls preload="metadata" src="/media/my-post/clip.mp4"></video>
|
||
*片头三秒试拍*
|
||
|
||
<audio controls preload="metadata" src="/media/my-post/voice.mp3"></audio>
|
||
*朗读：面纱选段*
|
||
```
|
||
|
||
- `preload="metadata"` 必写（不预拖流量，只取时长/首帧）
|
||
- 样式已全局处理（视频全宽圆角黑底、音频胶囊条）
|
||
- /media/ 命名空间同时覆盖"仓内小文件"与"仓外 store 大文件"（见体积纪律表）
|
||
|
||
## 体积纪律（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`）
|