Astro Markdown 进阶技巧：7个让博客变专业的实用方法

1
<div class="warning">
2
  <p>注意：这个操作会删除所有数据！</p>
3
</div>

1
import Alert from '@/components/Alert.astro';
2

3
<Alert type="warning">
4
  注意：这个操作会删除所有数据！
5
</Alert>

1
npx astro add mdx

1
import { defineConfig } from 'astro/config';
2
import mdx from '@astrojs/mdx';
3

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

1
---
2
title: 测试MDX
3
---
4

5
# 这是 MDX 测试
6

7
普通的 Markdown 文本。
8

9
export const greeting = "你好";
10

11
现在可以用变量了：{greeting}！
12

13
<div style="padding: 1rem; background: #f0f0f0;">
14
  这是一个 JSX 元素
15
</div>

1
import { defineConfig } from 'astro/config';
2
import mdx from '@astrojs/mdx';
3

4
export default defineConfig({
5
  integrations: [mdx()],
6
  markdown: {
7
    shikiConfig: {
8
      theme: 'dracula', // 可选：github-dark, nord, monokai, dracula 等
9
    },
10
  },
11
});

1
markdown: {
2
  shikiConfig: {
3
    themes: {
4
      light: 'github-light',
5
      dark: 'github-dark',
6
    },
7
  },
8
},

1
npm install shiki

1
import { defineConfig } from 'astro/config';
2
import mdx from '@astrojs/mdx';
3
import { transformerNotationHighlight } from '@shikijs/transformers';
4

5
export default defineConfig({
6
  integrations: [mdx()],
7
  markdown: {
8
    shikiConfig: {
9
      theme: 'github-dark',
10
      transformers: [transformerNotationHighlight()],
11
    },
12
  },
13
});

1
```javascript
2
function hello() {
3
  console.log('这行是普通的');
4
  console.log('这行会高亮显示'); // [!code highlight]
5
}
6
```

1
import { transformerNotationDiff, transformerNotationHighlight } from '@shikijs/transformers';
2

3
markdown: {
4
  shikiConfig: {
5
    theme: 'github-dark',
6
    transformers: [
7
      transformerNotationHighlight(),
8
      transformerNotationDiff(),
9
    ],
10
  },
11
},

1
```javascript
2
function calculate(a, b) {
3
  return a + b; // [!code --]
4
  return a * b; // [!code ++]
5
}
6
```

1
import { transformerNotationFocus } from '@shikijs/transformers';
2

3
// 添加到 transformers 数组
4
transformers: [
5
  transformerNotationFocus(),
6
],

1
```javascript
2
function process() {
3
  console.log('这行会变灰');
4
  console.log('这行正常显示'); // [!code focus]
5
  console.log('这行也变灰');
6
}
7
```

1
npx astro add astro-expressive-code

1
---
2
interface Props {
3
  type?: 'info' | 'warning' | 'error';
4
}
5

6
const { type = 'info' } = Astro.props;
7

8
const styles = {
9
  info: 'bg-blue-50 border-blue-200 text-blue-800',
10
  warning: 'bg-yellow-50 border-yellow-200 text-yellow-800',
11
  error: 'bg-red-50 border-red-200 text-red-800',
12
};
13
---
14

15
<div class={`border-l-4 p-4 ${styles[type]}`}>
16
  <slot />
17
</div>

1
---
2
title: 我的技术文章
3
---
4

5
import Alert from '@/components/Alert.astro';
6

7
# 文章标题
8

9
这是普通的文章内容。
10

11
<Alert type="warning">
12
  注意：运行这个命令前请备份数据！
13
</Alert>
14

15
<Alert type="info">
16
  提示：你也可以在组件里用 **Markdown 语法**，很方便。
17
</Alert>

1
import Counter from '@/components/Counter.tsx';
2

3
<Counter client:load initialCount={0} />

1
src/
2
├── components/
3
│   ├── mdx/
4
│   │   ├── Alert.astro
5
│   │   ├── CodeCompare.astro
6
│   │   ├── Callout.astro
7
│   │   └── Tabs.astro
8
│   └── ...其他组件

1
---
2
interface Props {
3
  level: 1 | 2 | 3 | 4 | 5 | 6;
4
  id?: string;
5
}
6

7
const { level, id } = Astro.props;
8
const Tag = `h${level}` as any;
9
---
10

11
<Tag id={id} class="group relative">
12
  <slot />
13
  {id && (
14
    <a href={`#${id}`} class="ml-2 opacity-0 group-hover:opacity-100 transition-opacity">
15
      #
16
    </a>
17
  )}
18
</Tag>

1
---
2
title: 文章标题
3
---
4

5
import CustomHeading from '@/components/CustomHeading.astro';
6

7
export const components = {
8
  h2: (props) => <CustomHeading level={2} {...props} />,
9
  h3: (props) => <CustomHeading level={3} {...props} />,
10
};
11

12
## 这是二级标题
13

14
鼠标悬停在标题上，会出现 # 锚点链接。
15

16
### 这是三级标题
17

18
所有 h2 和 h3 都自动应用了自定义样式。

1
---
2
interface Props {
3
  href?: string;
4
}
5

6
const { href } = Astro.props;
7
const isExternal = href?.startsWith('http');
8
---
9

10
<a href={href} target={isExternal ? '_blank' : undefined} rel={isExternal ? 'noopener noreferrer' : undefined}>
11
  <slot />
12
  {isExternal && <span class="ml-1 text-xs">↗</span>}
13
</a>

1
import ExternalLink from '@/components/ExternalLink.astro';
2

3
export const components = {
4
  a: ExternalLink,
5
};
6

7
[这是内部链接](/about)
8
[这是外部链接](https://example.com) ← 会自动加 ↗ 图标

1
npm install remark-math rehype-katex katex

1
import { defineConfig } from 'astro/config';
2
import mdx from '@astrojs/mdx';
3
import remarkMath from 'remark-math';
4
import rehypeKatex from 'rehype-katex';
5

6
export default defineConfig({
7
  integrations: [mdx()],
8
  markdown: {
9
    remarkPlugins: [remarkMath],
10
    rehypePlugins: [rehypeKatex],
11
  },
12
});

1
<link
2
  rel="stylesheet"
3
  href="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.css"
4
  crossorigin="anonymous"
5
/>

1
质能方程：$E = mc^2$
2

3
二次方程的解：$x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$

1
$$
2
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
3
$$
4

5
$$
6
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
7
$$

1
npm install rehype-mermaid

1
import { defineConfig } from 'astro/config';
2
import mdx from '@astrojs/mdx';
3
import rehypeMermaid from 'rehype-mermaid';
4

5
export default defineConfig({
6
  integrations: [mdx()],
7
  markdown: {
8
    rehypePlugins: [
9
      [rehypeMermaid, { strategy: 'img-svg' }]
10
    ],
11
  },
12
});

1
```mermaid
2
graph TD
3
    A[开始] --> B{是否安装MDX}
4
    B -->|是| C[配置代码高亮]
5
    B -->|否| D[安装MDX]
6
    D --> C
7
    C --> E[完成]
8
```

1
```mermaid
2
sequenceDiagram
3
    用户->>浏览器: 访问页面
4
    浏览器->>服务器: 请求HTML
5
    服务器->>浏览器: 返回渲染后的页面
6
    浏览器->>用户: 显示内容
7
```

1
npm install -D playwright

1
import { defineCollection, z } from 'astro:content';
2

3
const blog = defineCollection({
4
  type: 'content', // 表示这是内容文件（Markdown/MDX）
5
  schema: z.object({
6
    title: z.string(),
7
    description: z.string(),
8
    pubDate: z.date(),
9
    tags: z.array(z.string()).optional(),
10
    draft: z.boolean().default(false),
11
  }),
12
});
13

14
export const collections = { blog };

1
---
2
title: Astro MDX 进阶教程
3
description: 学习 MDX 的高级用法
4
pubDate: 2025-12-02
5
tags: [Astro, MDX, 教程]
6
---
7

8
import Alert from '@/components/Alert.astro';
9

10
# {frontmatter.title}
11

12
<Alert type="info">
13
  发布日期：{frontmatter.pubDate.toLocaleDateString()}
14
</Alert>

1
---
2
import { getEntry } from 'astro:content';
3

4
const entry = await getEntry('blog', 'my-mdx-article');
5
const { Content, headings } = await entry.render();
6
---
7

8
<aside>
9
  <h2>目录</h2>
10
  <ul>
11
    {headings.map(h => (
12
      <li style={`margin-left: ${(h.depth - 1) * 1}rem`}>
13
        <a href={`#${h.slug}`}>{h.text}</a>
14
      </li>
15
    ))}
16
  </ul>
17
</aside>
18

19
<article>
20
  <Content />
21
</article>

1
---
2
title: 我的文章
3
---
4

5
import { Image } from 'astro:assets';
6
import cover from './cover.jpg';
7

8
<Image src={cover} alt="封面图" width={800} height={600} />

1
export default defineConfig({
2
  integrations: [
3
    mdx({
4
      optimize: true,
5
    }),
6
  ],
7
});