Astro Markdown 与 MDX

直接渲染 Markdown

有了内容集合（Astro 内容集合），就可以把文章正文渲染到页面，使用 <Content /> 组件。条目对象的 render() 方法在上篇内容集合里讲过，它返回 { Content } 组件。

---
// src/pages/blog/[id].astro
import { getCollection } from 'astro:content';

// getStaticPaths 返回要生成的每个页面：params 是网址参数，props 是传给页面的数据
export async function getStaticPaths() {
  const posts = await getCollection('blog');
  return posts.map((post) => ({
    params: { id: post.id },
    props: { post },
  }));
}

const { post } = Astro.props;
const { Content } = await post.render(); // render() 返回 { Content } 组件，用来渲染 Markdown 正文
---
<article>
  <h1>{post.data.title}</h1>
  <Content />
</article>

<Content /> 会把 Markdown 渲染成 HTML 并插入页面。

给文章套布局

通常文章页会用一个专门的布局，包含标题、日期等。

---
const { post } = Astro.props;
const { Content } = await post.render(); // render() 返回 { Content } 组件，用来渲染 Markdown 正文
---
<PostLayout title={post.data.title} date={post.data.date}>
  <Content />
</PostLayout>

用 MDX 写更灵活的内容

MDX 是「能在 Markdown 里写组件」的格式，文件后缀为 .mdx。装好 MDX 集成后，可以在文章里直接引入并使用组件。

---
title: 带组件的文档
---

import Callout from '../../components/Callout.astro';

<Callout>这是一条提示</Callout>

普通 Markdown 语法依然可用。

这让文档不再只是文字，可以嵌入交互演示、代码沙盒等。

代码高亮

Astro 内置对 Markdown 代码块的高亮支持，写代码块时标注语言即可。

```js
console.log('hello astro');
```

构建后会生成带高亮标记的 HTML，你也可以配置自己喜欢的高亮主题。

启用 MDX 集成

要在项目里使用 MDX，需要先启用 MDX 集成。

// astro.config.mjs
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  integrations: [mdx()],
});

Markdown 与 MDX 对比

• 纯文章、教程：普通 Markdown 足够，简单纯粹。
• 需要嵌入组件、交互示例的文档：用 MDX。