# 写作指南：在文章里插入图片 / 视频 / 音频 > 适用：`content/posts/*.md`（书评与技术轨通用）。资产目录约定 + 三种媒体的写法 + 体积纪律。 ## 写作模板（从这里开始，2026-11-02 起） 别从空白文件起步——**复制现成的模板**： ```bash cp content/posts/writing-template.md content/posts/my-new-post.md # 改 frontmatter 的 title / pubDate / tags / description，删掉不需要的段落 ``` 模板本身是一篇真文章（线上读：`/archives/writing-template/`），每节都在跑一种能力，你看到的效果就是源码的效果：标题层级、彩色强调、字族切换、引用、列表、代码窗条、表格、图片放大、链接卡片、`
` 折叠、分隔线。 写之前只需记住三条纪律： - **彩色不限次数**（2026-11-02 用户拍板取消原来的"一页最多三处"）：正文想用多少处颜色都可以；仍守的是另一条——**外壳灰阶**（导航/页脚/按钮/背景不染色），因为外壳是气质，正文是表达 - **整页换字族要谨慎**：会给访问者拉一份中文字体（汇文明朝整页约 420KB，已子集化） - **折叠放细节不放结论**：`
` 里的内容可能永远没人展开 ## 隐藏文章（两种写法，任选其一） 不想让某篇出现在首页/归档/书架/RSS/sitemap： - frontmatter 写 `hidden: true`（后台有开关） - 或在 `tags` 里加一个 `hidden` 页面本身仍会生成，链接可以直接分享给别人；想连页面都不生成，用 `draft: true`（草稿）。 **隐藏与置顶同开时，以隐藏为准**（2026-11-04 修复：此前隐藏开关是假的，隐藏+置顶会照样显示还排第一）。 ## 置顶文章 首页、归档、书架三处列表默认按日期倒序。想让某篇长期排在最前，frontmatter 加一行： ```yaml pinned: true ``` 语义边界（刻意设计成这样）： - **只影响列表顺序**，不改 `pubDate`、不改 URL、不影响 RSS 的时间序列（订阅者不会看到时间错乱） - 多篇同时置顶时，它们内部仍按日期倒序 - 列表里会显示一个灰阶「置顶」小徽标，取消置顶后立刻回到时间序 - 后台「文章」编辑页有「置顶」开关，不必手改 frontmatter ## 目录约定 ``` 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)

图：外滩的傍晚

← 显式图注类（居中小字） ``` - 图注可选；**必须用 `

…

`**（2026-11-02 起） - ⚠️ 旧写法 `*斜体独立段*` 已不再自动当图注：此前它会把正文里所有独占成段的斜体都变成块级居中（用户实测的排版 bug），现在斜体恢复为正常行内强调 - 压缩纪律：入仓前长边 ≤2400px（可跑 `python3 scripts/photos_ingest.py`，对 posts 资产同样有效的思路，图片请自行用同规格压缩） ## 视频 / 音频 markdown 原生不认视音频，写 HTML 标签；**raw HTML 的相对路径不走 Astro 资产管线**（只有 `![]()` 图片语法走），所以媒体文件放 **`public/media/{slug}/`** （构建原样拷入 dist），引用用绝对路径 `/media/...`： ``` public/media/my-post/clip.mp4 ← 文件放这里 ``` ```html *片头三秒试拍* *朗读：面纱选段* ``` - `preload="metadata"` 必写（不预拖流量，只取时长/首帧） - **图注警示**：斜体图注行内不要裸写 `