何时使用 MDX
大多数文章应保持 Markdown。只有 Astro 组件需要内联出现时才改用 MDX。
Markdown 足以应付大多数写作:标题、段落、链接、列表、引用、代码、图片。默认请留在 Markdown。
当 Astro 组件需要出现在文章内部——不是旁边,不是文末,而是正文所指的确切位置——再改用 MDX。
本文件是 MDX。请看 FigureNote 在这里的效果:
组件内联嵌入。文章继续。这就是 MDX 的唯一用途。
如何把文章改成 MDX
-
将文件从
.md重命名为.mdx。 -
在 frontmatter 之后导入组件:
import FigureNote from '../../../components/FigureNote.astro'; -
在正文中像 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 是小升级,不是默认选项。只在升级物有所值时使用。