建站 2026年6月20日 约 3388 字正文

如何在这个博客写一篇 MDX 文章

从文件位置、Frontmatter、正文结构到发布前检查，整理一份适合当前 Astro 博客的 MDX 写作流程。

#博客 #MDX #写作 #Astro
桌面上的笔记本和写作工具

这篇文章整理一下在当前博客里写一篇 MDX 文章的流程。

Firefly 的写作文档给了一个很清楚的方向：文章文件放在内容目录里，顶部写 Frontmatter，下面用 Markdown 或 MDX 写正文。这个博客也是类似思路，只是字段名称按当前 Astro 内容集合做了适配。

文章放在哪里

中文文章放在：

src/content/posts/

英文文章放在：

src/content/posts/en/

文件名建议使用英文小写短横线，比如：

how-to-write-mdx-post.mdx

这样生成链接时更稳定，也更适合长期维护。

先写 Frontmatter

每篇文章顶部都要写一段 YAML Frontmatter，用三条横线包起来：

---
title: "文章标题"
description: "一句话说明这篇文章写什么。"
pubDate: 2026-06-20
updatedDate: 2026-06-20
language: zh
translationKey: article-slug
category: "分类"
tags:
  - 标签
draft: false
featured: false
cover:
  src: "https://cdn.example.com/images/example.jpg"
  alt: "封面图说明"
---

这些字段里，最重要的是：

  • title：文章标题。
  • description：文章摘要，会用于列表、搜索和页面描述。
  • pubDate：发布时间。
  • updatedDate：更新时间，可以不写，但文章修改后建议补上。
  • language：中文写 zh，英文写 en。
  • translationKey：同一篇文章的不同语言版本使用同一个 key。
  • category：文章分类。
  • tags：文章标签，可以写多个。
  • draft：是否草稿。
  • featured：是否作为精选文章展示。
  • cover：封面图地址和说明。

Firefly 文档里常见的是 published、updated、image、pinned 这样的字段；当前博客对应使用的是 pubDate、updatedDate、cover、featured。写文章时要按当前项目字段来，不然构建时可能识别不了。

正文怎么写

Frontmatter 下面就是正文。普通 Markdown 写法都可以用：

## 小标题


这里是一段正文。


- 第一条
- 第二条
- 第三条


> 这里是一段引用。

代码块也可以直接写：

```ts
const title = "如何写一篇 MDX 文章";
console.log(title);
```

如果以后需要在文章里引入交互组件，MDX 也支持这样做。不过日常写作不需要急着使用组件，先把标题、段落、列表、引用和代码块写清楚就够了。

Firefly 风格增强写法

现在这个博客也补上了接近 Firefly 的文章增强能力：数学公式、Mermaid 图表、提示框、GitHub 卡片、iframe 嵌入和剧透折叠。

数学公式

行内公式可以这样写：$E = mc^2$。

渲染效果是：E=mc2E = mc^2。

块级公式可以这样写：

$$
\int_0^1 x^2 dx = \frac{1}{3}
$$

渲染效果是：

∫01x2dx=13\int_0^1 x^2 dx = \frac{1}{3}

Mermaid 图表

用 mermaid 代码块写图表：

```mermaid
flowchart LR
  A[写文章] --> B[保存 MDX]
  B --> C[Astro 构建]
  C --> D[发布页面]
```

渲染效果是：

flowchart LR
  A[写文章] --> B[保存 MDX]
  B --> C[Astro 构建]
  C --> D[发布页面]

提示框

提示框使用 ::: 容器语法：

:::tip 写作提示
先把内容写清楚，再补封面、标签和更复杂的组件。
:::

渲染效果是：

:::tip 写作提示 先把内容写清楚，再补封面、标签和更复杂的组件。 :::

可用类型包括 note、info、tip、warning、danger。

GitHub 仓库卡片

在 MDX 里导入组件后，可以插入仓库卡片：

import GithubCard from "@/components/writing/GithubCard.astro";


<GithubCard repo="withastro/astro" />

渲染效果是：

withastro/astro GitHub repository Repository Stars -- Forks --

iframe 嵌入

需要嵌入视频或外部页面时，用封装组件：

import FireflyIframe from "@/components/writing/FireflyIframe.astro";


<FireflyIframe title="Astro 官网" src="https://astro.build/" />

渲染效果是：

Astro 官网

剧透和折叠内容

需要隐藏答案、补充说明或较长内容时，用 Spoiler：

import Spoiler from "@/components/writing/Spoiler.astro";


<Spoiler title="展开查看补充说明">这里是默认折叠的内容。</Spoiler>

渲染效果是：

展开查看补充说明

这里是默认折叠的内容。适合放答案、剧透、补充材料，或者不想打断正文节奏的说明。

一个推荐的文章结构

我自己更喜欢按这个顺序写：

  1. 用一两段说明这篇文章为什么要写。
  2. 用二级标题拆分主要内容。
  3. 每个小节只讲一个重点。
  4. 需要总结时，最后加一个简短收束。

比如一篇建站记录可以这样组织：

## 为什么要改


说明背景和问题。


## 做了哪些调整


按模块记录改动。


## 最后留下的规则


整理经验和后续注意事项。

这样的结构不会太花哨，但读起来很稳。对未来的自己也友好：过几个月回来改文章时，很容易找到要补的地方。

发布前检查

写完后可以快速检查几件事：

  • 标题是不是清楚。
  • 摘要能不能说明文章内容。
  • 日期是否正确。
  • 分类和标签是否统一。
  • 封面图是否能公开访问。
  • alt 文本是否能描述图片。
  • 草稿文章是否保留 draft: true。

如果是公开仓库，还要额外确认文章里没有密码、Token、私密链接、后台截图、未处理的照片定位信息。

最小可用模板

以后新建中文文章，可以从这份最小模板开始：

---
title: "文章标题"
description: "一句话说明这篇文章写什么。"
pubDate: 2026-06-20
language: zh
translationKey: article-slug
category: "随笔"
tags:
  - 记录
draft: false
featured: false
---


这里写开头。


## 小标题


这里写正文。

写博客不用每次都从复杂模板开始。先把文章写出来，再补封面、标签、更新时间和更细的结构，也是一种很舒服的节奏。