同一组照片，多种呈现方式

支撑文字的照片，最好和文字放在一起。文件夹媒体画廊做的就是这件事：文件放在内容条目下的文件夹里，写一条 ::gallery，再选择这组图在页面上如何呈现。

这和 Markdown Slides 是同一类思路：作者掌握一份记录，读者可以有不止一种读法。Slides 把页面变成讲稿；Gallery 把文件夹变成图组的呈现。

本页是这项能力的唯一专题样例：浏览布局、large、stage、story —— 同一模型，多种呈现。参数表与每种模式的可运行样例也见媒体画廊指南。

从文件夹开始

在 content.md 旁建 media/，放入图片，按希望的顺序命名，然后：

::gallery{folder="media" layout="mosaic"}

运行时会把指令展开成媒体块。路径仍相对条目本身。不必为了在一篇文章里展示，先把整组图丢进站点级媒体库。

本页图片在仓库内本文的文件夹下，不走外链。站点构建时，这些文件与内容一起发布。

浏览布局

小图网格适合扫视，也适合点击放大（lightbox）：点开一张，再用方向键在当前画廊内翻页。浏览布局默认打开 lightbox（lightbox=false 可关）。

Mosaic

主图一块，周围陪衬。末行不完整时会拉满，整块仍是矩形。

Grid

等格；用 cols 调疏密。

Pair

双联对仗。适合前后对比或呼应。

Masonry

画幅不一致时用自然高度分栏，并尽量压低列高差。

Film

Contact sheet，快速扫完整组。

Large

每张需要单独呼吸时的全宽叠放。lightbox 默认关（本身已是全宽）；需要时用 lightbox=true。

Stage

一次一屏的全视口 plate。说明文字叠在图上（角或边），由每文件 sidecar 控制——不是图下方一行被裁切的小字。lightbox 默认关，避免再叠一层全屏。

sidecar 形状：

---
title: Ridge
overlay: bottom-left
tone: dark
---

可写在 plate 上的第二行。

全视口 plate。往下滚，或把这一页当作一整块媒体。

Story

全宽滚动的高 plate。与 stage 相同的叠加文案——通过 sidecar 的 overlay / tone 把标题与正文叠在图上。媒体仍在条目内。

杂志式全宽滚动 plate。路线由道路本身决定。

作者能控制什么

::gallery{folder="media" layout="mosaic"}
::gallery{folder="media" layout="pair"}
::gallery{folder="media" layout="grid" cols="3"}
::gallery{folder="media" layout="masonry"}
::gallery{folder="media" layout="film"}
::gallery{folder="media" layout="large"}
::gallery{folder="stage" layout="stage"}
::gallery{folder="story" layout="story"}

什么时候别用

图组只有一份真相

照片变了，改文件夹。版式变了，改一个属性。文章与文档样例可以共用同一模式，而不维护平行导出。

这就是这项能力：写作旁边的一个文件夹，加上几套诚实的呈现方式——包括可选 lightbox——让页面可以像杂志跨页、像 contact sheet，或像全宽故事，而不离开内容模型。