MDX 写作指南

1. 新建文章

博客文章以 .mdx 文件存放在 src/content/blog/ 下。文件名即 URL，建议用英文 slug（连字符分隔）：

src/content/blog/mw-feature-announcement.mdx  →  /blog/mw-feature-announcement

最快方式：复制模板改名。

cp src/content/blog/_template.mdx src/content/blog/my-post.mdx

2. Frontmatter 字段

文章顶部 --- 之间的 YAML 区域为 frontmatter，经 Zod 校验。下面是完整字段表：

字段	必填	说明
`title`	✅	文章标题（详情页 / 列表 / SEO）
`description`	✅	一句话摘要。详情页副标题支持行内 Markdown（`加粗`、`斜体`、`代码`、`[链接]()`）；列表摘要与 SEO meta 仍用纯文本
`pubDate`	✅	发布日期，格式 `YYYY-MM-DD`（横杠，勿用斜杠）
`tags`	—	标签数组，建议复用已有标签
`author`	—	作者，默认 `m&WDAO`
`draft`	—	草稿，默认 `false`；`true` 时本地 dev 可见、生产构建自动隐藏
`updatedDate`	—	修订日期，影响 SEO 的 `dateModified`
`cover`	—	封面图路径，如 `/images/blog/my-post/cover.png`

示例：

---
title: "EcoFi 协议：去信任化的协作基石"
description: "深度解析 **EcoFi 协议** 的治理与价值捕获算法。"
pubDate: 2026-06-22
tags: ["机制", "EcoFi"]
---

3. Markdown / MDX 语法

正文使用标准 Markdown，同时支持 MDX（可在正文中 import 并渲染 Astro 组件）。

常用语法速查

效果	写法
加粗	`加粗`
斜体	`斜体`
`行内代码`	`行内代码`
链接	`[链接](https://example.com)`
无序列表	`- 列表项`
有序列表	`1. 列表项`
引用块	`> 引用内容`
代码块	```ts 代码 ```
表格	`\| A \| B \|`
分割线	`---`
图片	`![alt](/images/...png)`

数学公式（KaTeX）

行内公式用 $...$ ，块级公式用 $$...$$。由 remark-math + rehype-katex 渲染：

行内：$E = mc^2$

块级：
$$
\sum_{i=1}^{n} x_i = \frac{n(n+1)}{2}
$$

渲染效果：

行内：$E = mc^2$

MDX 组件（正文中导入 Astro 组件）

在 MDX 文件顶部（frontmatter 下方）import，正文中即可使用：

import LinkCard from '@/components/LinkCard.astro';

正文中直接写：

<LinkCard
  href="https://example.org/post"
  title="标题"
  description="摘要"
  variant="bare"
/>

4. LinkCard 引用卡片

转载或引用外部文章时，用 <LinkCard /> 渲染预览卡片，比裸链接更直观。三种变体：

变体 ① media（带封面图）

源码：

<LinkCard
  href="https://foresightnews.pro/article/detail/97058"
  title="m&W 启动 EcoFi 计划，构建「无需信任」的分布式文明基石"
  description="ForesightNews · 九位创世节点完成集结，完整白皮计划书。"
  variant="media"
  thumb="/images/whitepaper/ecofi-engine.png"
/>

↓ 实际渲染效果：

foresightnews.prom&W 启动 EcoFi 计划，构建「无需信任」的分布式文明基石

ForesightNews · 九位创世节点完成集结，完整白皮计划书。

变体 ② bare（无封面图，最通用）

源码：

<LinkCard
  href="https://example.org/some-long-article"
  title="数字文明进阶与秩序危机：我们为什么需要 EcoFi"
  description="人类社会正处在向数字文明进阶的奇点。"
  variant="bare"
/>

↓ 实际渲染效果：

example.org数字文明进阶与秩序危机：我们为什么需要 EcoFi

人类社会正处在向数字文明进阶的奇点。

变体 ③ mini（紧凑单行，段落内轻量引用）

源码：

<LinkCard
  href="https://vitalik.ca/general/2020/09/11/verification.html"
  title="Mechanism Design: A Foundational Essay"
  variant="mini"
/>

↓ 实际渲染效果：

vitalik.caMechanism Design: A Foundational Essay

字段说明

字段	必填	说明
`href`	✅	原文链接（点击在新标签打开）
`title`	✅	卡片标题
`description`	—	摘要，`bare` / `media` 推荐填，`mini` 不显示
`variant`	—	`media`（默认）/ `bare` / `mini`
`site`	—	域名展示文案；省略则自动从 `href` 提取
`thumb`	—	封面图路径，仅 `media` 变体显示

⚠️ 封面图务必本地化：第三方平台（公众号、微博、Twitter 等）有 Referer 防盗链，直接引用会 403 或裂图。把图片下载到 public/images/blog/<slug>/ 下，thumb 填本地路径。组件内置 onerror 兜底，加载失败时自动降级为无图卡片。

5. 图片放置

内容图片统一放在 public/images/，通过 /images/ 路径访问：

public/
├── images/
│   ├── whitepaper/          # 白皮书图片
│   │   └── ecofi-engine.png
│   └── blog/
│       └── <slug>/           # 按文章 slug 分文件夹
│           └── cover.png

在 MDX 中引用：

![图片说明](/images/whitepaper/ecofi-engine.png)

带居中说明的 figure：

<figure>
  <img src="/images/whitepaper/evolution-path.png" alt="演进路径" loading="lazy" />
  <figcaption>m&W 演进路径：1.0 → 2.0 → 3.0</figcaption>
</figure>

完整图片规范见 docs/images.md。

6. 发布流程

cp _template.mdx my-post.mdx —— 复制模板
修改 frontmatter（title / description / pubDate / tags）
撰写正文
pnpm dev 本地预览
将 draft: true 改为 draft: false（或删掉）
提交 PR / commit