← 全部文章

何时使用 MDX

大多数文章应保持 Markdown。只有 Astro 组件需要内联出现时才改用 MDX。

Markdown 足以应付大多数写作:标题、段落、链接、列表、引用、代码、图片。默认请留在 Markdown。

当 Astro 组件需要出现在文章内部——不是旁边,不是文末,而是正文所指的确切位置——再改用 MDX。

本文件是 MDX。请看 FigureNote 在这里的效果:

组件内联嵌入。文章继续。这就是 MDX 的唯一用途。

如何把文章改成 MDX

  1. 将文件从 .md 重命名为 .mdx。

  2. 在 frontmatter 之后导入组件:

    import FigureNote from '../../../components/FigureNote.astro';
  3. 在正文中像 HTML 标签一样使用:

    <FigureNote title="Tip">Inline content goes here.</FigureNote>

切换就这些。组件周围的 Markdown 照常可用。

示例组件

入门模板包含一个正文组件:FigureNote。故意做得很小。

src/components/FigureNote.astro:

---
interface Props {
title?: string;
}
const { title = 'Note' } = Astro.props;
---
<aside class="figure-note">
<p class="figure-note__label">{title}</p>
<div class="figure-note__body">
<slot />
</div>
</aside>

样式与 FigureNote.astro 组件放在一起,使用与主题其余部分相同的 token。若修改 --color-blue 或 --label-tertiary,注释块会跟着变。

自己做一个

好用的正文组件应小巧、读起来像 HTML 元素,并且能靠澄清说明而值得占用版面。

合适场景:

  • 具有特定语气的标注框(说明、提示、警告)。
  • 并排对比块。
  • 比 *说明* 更丰富的图注。
  • 需要与块引用不同样式的引文。

请跳过:

  • 段落之间的装饰。
  • 重复正文已说内容的卡片。
  • 任何带内部状态、网络请求或独立路由的东西。

若组件需要状态或行为,通常应放在页面路由里,而不是文章里。文章可以链接过去。

文件放在哪

导入 MDX 的 Astro 组件可放在 src/components/ 下任意位置。入门模板也把正文专用组件放在那里。FigureNote.astro 是其中之一。

组件自有 CSS 可与 .astro 文件放在同一处,作为作用域 <style> 块:

---
const { title = 'Note' } = Astro.props;
---
<aside class="figure-note">
<p class="figure-note__label">{title}</p>
<div class="figure-note__body">
<slot />
</div>
</aside>
<style>
.figure-note {
border-left: 2px solid var(--color-blue);
}
</style>

Astro 将样式限定在组件输出上,注释块可以自带呈现方式,无需添加全局选择器。

保持源码可读

MDX 文件仍是文档。每篇文章两三个自定义块就够。一旦需要十个组件和五十行 JSX,它就不再是写作,而成了页面模板。

那时应把内容移到 src/pages/ 下的真实路由,再从 Markdown 文章链接过去。

何时 Markdown 更合适

若文章不需要自定义块,就留在 Markdown:

  • 在编辑器里更快阅读。
  • 更容易在不同站点间迁移。
  • 无需跟踪 import。
  • 通过主题以相同方式渲染。

MDX 是小升级,不是默认选项。只在升级物有所值时使用。