MDX 图文混排样例大全

这篇文章只做一件事：集中展示在这个仓库里已经能直接运行的图文混排写法。你可以把它当作一个 MDX cookbook，需要哪段就复制哪段。

Quick map

Markdown 图片加说明
全宽大图加段落
左文右图双栏
左图右文双栏
图片旁边的要点列表
双图并排展示
错落卡片式图文
Callout 配图
Tabs 中切换布局
步骤流程图文
多图网格
截图与代码对照

Markdown 图片加说明

这是最简单也最稳的一种方式。适合在正常正文里插入一张图，不改变排版节奏。

Figma workflow hero

最基础的图文混排：正文中直接插图，然后单独补一行说明。

适合场景：文章中穿插一张示意图、流程图、截图，不需要额外布局控制。

这是最简单也最稳的一种方式。适合在正常正文里插入一张图，不改变排版节奏。

![Figma workflow hero](https://img.scofieldfee.com/blog/dont-translate-figma-directly-to-pages/hero-v1.webp)

<Caption>最基础的图文混排：正文中直接插图，然后单独补一行说明。</Caption>

全宽大图加段落

如果你希望图片像一个章节封面，而不是普通插图，可以用 figure 包一层，让视觉分量更强。

Feature image example — 适合做章节开场图或案例导入图，视觉重心会更强。

在长文里，这种写法通常放在一个新 section 开头，让读者先看到画面，再进入文字说明。

<figure className="not-prose my-10 overflow-hidden rounded-(--radius-media) border border-border/70 bg-muted/25">
  <img
    src="https://img.scofieldfee.com/blog/dont-translate-figma-directly-to-pages/feature-v1.webp"
    alt="Feature image example"
    className="w-full"
  />
  <Caption>适合做章节开场图或案例导入图，视觉重心会更强。</Caption>
</figure>

在长文里，这种写法通常放在一个新 section 开头，让读者先看到画面，再进入文字说明。

左文右图双栏

当图片和说明文字需要同时出现时，双栏是最常用的写法。这里的关键是外层加 not-prose，避免全局 prose 改写布局。

左侧放解释文字，右侧放配图，是最常见的图文并排结构。它适合讲清楚一个方法、一个阶段，或者一段较短的操作流程。

在这个容器内部，建议直接使用 JSX 的 <p>，这样你能完全控制间距和排版，不会被 Markdown 段落规则影响。

如果移动端需要回到单列，这个写法已经天然兼容，小屏会自动堆叠。

LaunchVault blog layout — 双栏布局通常用来解释截图、首页模块或结构图。

适合场景：方法说明、页面模块拆解、产品截图解说。

<div className="not-prose my-10 grid gap-6 md:grid-cols-[1.1fr_0.9fr] md:items-start">
  <div className="space-y-4 text-[15px] leading-8 text-(--foreground-soft)">
    <p>左侧放解释文字，右侧放配图，是最常见的图文并排结构。</p>
    <p>在这个容器内部，建议直接使用 JSX 的 <p>。</p>
    <p>移动端会自动堆叠回单列。</p>
  </div>

  <figure className="overflow-hidden rounded-(--radius-media) border border-border/70 bg-muted/25">
    <img src="https://pub-3abb355f0716495d8baf218afe070076.r2.dev/launchvault-blog-v10.png" alt="LaunchVault blog layout" className="w-full" />
    <Caption>双栏布局通常用来解释截图、首页模块或结构图。</Caption>
  </figure>
</div>

左图右文双栏

只要把列顺序交换一下，就能得到完全不同的视觉节奏。长文里左右交替出现，会比整篇都一个方向更有层次。

Hero image on the left — 把图片放左边，正文放右边，阅读重心会先被视觉吸住。

左图右文更像杂志排版。它更适合那些图片本身信息密度比较高、你希望读者先看图再看解释的段落。

如果整篇文章会出现多段图文并排，建议左右方向交替使用，而不是每段都固定一边。

<div className="not-prose my-10 grid gap-6 md:grid-cols-[0.9fr_1.1fr] md:items-center">
  <figure className="overflow-hidden rounded-(--radius-media) border border-border/70 bg-muted/25">
    <img src="https://img.scofieldfee.com/blog/dont-translate-figma-directly-to-pages/hero-v1.webp" alt="Hero image on the left" className="w-full" />
    <Caption>把图片放左边，正文放右边，阅读重心会先被视觉吸住。</Caption>
  </figure>

  <div className="space-y-4 text-[15px] leading-8 text-(--foreground-soft)">
    <p>左图右文更像杂志排版。</p>
    <p>整篇文章里可以和上一种布局交替使用。</p>
  </div>
</div>

图片旁边的要点列表

有些时候右侧不是一段叙述，而是一组重点，这时把图片和列表并排会更清晰。

Key points

图片负责建立直觉，列表负责归纳重点。
这种写法特别适合产品能力介绍或设计拆解。
如果每一条都很短，读者扫读速度会比整段文字更快。
外层做成卡片后，整块内容会比普通双栏更集中。

<div className="not-prose my-10 grid gap-6 rounded-[28px] border border-border/70 bg-muted/20 p-5 md:grid-cols-[0.95fr_1.05fr] md:p-6">
  <figure className="overflow-hidden rounded-(--radius-media) border border-border/70 bg-background">
    <img src="https://img.scofieldfee.com/blog/dont-translate-figma-directly-to-pages/feature-v1.webp" alt="Feature detail" className="w-full" />
  </figure>

  <div className="space-y-4">
    <p className="font-mono text-[11px] tracking-widest text-muted-foreground">Key points</p>
    <ul className="space-y-3 text-[15px] leading-7 text-(--foreground-soft)">
      <li>图片负责建立直觉，列表负责归纳重点。</li>
      <li>这种写法特别适合产品能力介绍或设计拆解。</li>
    </ul>
  </div>
</div>

双图并排展示

如果你需要做前后对比、方案对比，或者同时展示两张参考图，双图并排会比上下堆叠更直观。

适合做版本对比、前后改版、不同视觉方向的并列展示。

<div className="not-prose my-10 grid gap-5 md:grid-cols-2">
  <figure className="overflow-hidden rounded-(--radius-media) border border-border/70 bg-muted/25">
    <img src="https://img.scofieldfee.com/blog/dont-translate-figma-directly-to-pages/hero-v1.webp" alt="First comparison image" className="w-full" />
    <Caption>方案 A：更偏封面感。</Caption>
  </figure>

  <figure className="overflow-hidden rounded-(--radius-media) border border-border/70 bg-muted/25">
    <img src="https://img.scofieldfee.com/blog/dont-translate-figma-directly-to-pages/feature-v1.webp" alt="Second comparison image" className="w-full" />
    <Caption>方案 B：更偏信息承载。</Caption>
  </figure>
</div>

<SourceNote>适合做版本对比、前后改版、不同视觉方向的并列展示。</SourceNote>

错落卡片式图文

如果你不想让页面全是标准双栏，可以做一点错落层次，让阅读节奏更像编辑排版而不是文档系统。

Editorial block

把图文块做成卡片，层次会更稳

错落感不一定要靠复杂动画，很多时候只需要让图片块和文字块拥有不同的边框、背景和高度，页面就会更有呼吸感。

这种写法适合专题文章、案例复盘或视觉导向较强的内容。

<div className="not-prose my-12 grid gap-5 md:grid-cols-[1fr_0.86fr]">
  <div className="rounded-[28px] border border-border/70 bg-background p-5 shadow-sm">
    <p className="font-mono text-[11px] tracking-widest text-muted-foreground">Editorial block</p>
    <h3 className="mt-4 font-serif text-2xl leading-tight text-foreground">把图文块做成卡片，层次会更稳</h3>
    <p className="mt-4 text-[15px] leading-8 text-(--foreground-soft)">这种写法适合专题文章、案例复盘或视觉导向较强的内容。</p>
  </div>

  <figure className="translate-y-4 overflow-hidden rounded-[32px] border border-border/70 bg-muted/25 md:translate-y-10">
    <img src="https://pub-3abb355f0716495d8baf218afe070076.r2.dev/launchvault-blog-v10.png" alt="Editorial card image" className="w-full" />
  </figure>
</div>

Callout 配图

有时你需要强调某个观点，但又不想只放一块纯文字提示框。把 Callout 和图片放到同一个网格里，会更适合做“提醒 + 示例”。

Note

当你需要同时表达一个提醒、一个结论和一个可视化示例时，这个组合会比纯文字 Callout 更完整。

<div className="not-prose my-10 grid gap-5 md:grid-cols-[0.95fr_1.05fr] md:items-start">
  <Callout title="什么时候该用这类布局？">
    当你需要同时表达一个提醒、一个结论和一个可视化示例时，这个组合会比纯文字 Callout 更完整。
  </Callout>

  <figure className="overflow-hidden rounded-(--radius-media) border border-border/70 bg-muted/25">
    <img src="https://img.scofieldfee.com/blog/dont-translate-figma-directly-to-pages/hero-v1.webp" alt="Callout with image" className="w-full" />
  </figure>
</div>

Tabs 中切换布局

如果你想把多种布局方案放在同一处对比，可以直接用项目已支持的 Tabs。这种写法适合做“同一内容的不同呈现方式”。

这是经典双栏，适合讲方法。

结构简单，复用成本低。

Card style

这是更偏专题或案例文章的图文块写法，适合强调层次和情绪。

<Tabs items={["双栏", "双图", "卡片"]}>
  <Tab value="双栏">{/* 放双栏布局 */}</Tab>
  <Tab value="双图">{/* 放双图布局 */}</Tab>
  <Tab value="卡片">{/* 放卡片布局 */}</Tab>
</Tabs>

步骤流程图文

教程类文章常常需要按步骤讲解，每步配一张截图。用编号圆圈 + 文字 + 图片的三栏网格，可以让操作流程一目了然。

打开 Figma，选中需要导出的目标 frame，确认图层命名和约束已经设好。

右侧面板选择 Export，格式设为 PNG 2x，点击导出按钮。

将导出的图片放入项目的 assets 目录，运行处理脚本完成压缩。

适合场景：操作指南、教程步骤、安装流程、工作流拆解。

<div className="not-prose my-10 space-y-8">
  <div className="grid gap-5 md:grid-cols-[auto_1fr_1fr] md:items-center">
    <span className="flex size-9 items-center justify-center rounded-full bg-primary text-sm font-bold text-primary-foreground">1</span>
    <p className="text-[15px] leading-8 text-(--foreground-soft)">第一步说明文字。</p>
    <img src="..." alt="Step 1" className="w-full rounded-(--radius-media) border border-border/70" />
  </div>
  <div className="grid gap-5 md:grid-cols-[auto_1fr_1fr] md:items-center">
    <span className="flex size-9 items-center justify-center rounded-full bg-primary text-sm font-bold text-primary-foreground">2</span>
    <p className="text-[15px] leading-8 text-(--foreground-soft)">第二步说明文字。</p>
    <img src="..." alt="Step 2" className="w-full rounded-(--radius-media) border border-border/70" />
  </div>
</div>

多图网格

当需要同时展示三张或更多图片时，双图并排不够用，三列网格更合适。适合多方案对比、UI 状态展示、设计探索记录。

小屏自动回落为两列，再小则堆叠为单列。

<div className="not-prose my-10 grid gap-4 sm:grid-cols-2 md:grid-cols-3">
  <figure className="overflow-hidden rounded-(--radius-media) border border-border/70 bg-muted/25">
    <img src="..." alt="Option A" className="w-full" />
    <Caption>方案 A</Caption>
  </figure>
  <figure className="overflow-hidden rounded-(--radius-media) border border-border/70 bg-muted/25">
    <img src="..." alt="Option B" className="w-full" />
    <Caption>方案 B</Caption>
  </figure>
  <figure className="overflow-hidden rounded-(--radius-media) border border-border/70 bg-muted/25">
    <img src="..." alt="Option C" className="w-full" />
    <Caption>方案 C</Caption>
  </figure>
</div>

截图与代码对照

技术文章里最常见的需求之一：左边放渲染效果截图，右边放对应代码。读者可以一边看效果一边看实现。

Source code

<figure className="rounded border">
<img src="..." className="w-full" />
<Caption>说明文字</Caption>
</figure>

适合场景：组件文档、CSS 技巧演示、前后对比代码走查。

<div className="not-prose my-10 grid gap-5 md:grid-cols-2 md:items-start">
  <figure className="overflow-hidden rounded-(--radius-media) border border-border/70 bg-muted/25">
    <img src="..." alt="渲染效果" className="w-full" />
    <Caption>实际渲染效果</Caption>
  </figure>

  <div className="space-y-3">
    <p className="font-mono text-[11px] tracking-widest text-muted-foreground">Source code</p>
    <div className="overflow-hidden rounded-(--radius-media) border border-border/70 bg-muted/10 p-4 text-sm leading-7">
      <pre><code>{`你的代码片段`}</code></pre>
    </div>
  </div>
</div>

最后几个实用建议

普通正文中插图，优先用 Markdown 图片加 Caption。
只要开始做并排布局，就给外层加 not-prose。
在 JSX 容器内部，正文尽量写成 <p>，不要混着依赖 Markdown 段落。
如果某种布局会反复出现，再考虑抽成单独组件；在那之前，MDX 里直接写 JSX 更快。
一篇文章里不要把所有样式都堆上去，选 2 到 3 种主布局反复使用，整体会更稳。