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

Firefly 风格写作能力完整演示

用一篇文章集中展示当前博客支持的数学公式、Mermaid 图表、提示框、GitHub 卡片、iframe 嵌入、剧透折叠和代码块增强。

#博客 #MDX #写作 #Firefly
屏幕上展示图表和代码的写作工作区

这篇文章专门用来演示当前博客已经补上的 Firefly 风格写作能力。

它不是说明文档的替代品，更像一张渲染样张：以后改样式、改 Markdown 管线、升级依赖时，只要打开这篇文章，就能快速确认每一种增强内容有没有正常显示。

数学公式

行内公式可以直接写在段落里，比如 E=mc2E = mc^2。它应该和普通文字自然排在同一行，而不是像代码一样生硬。

块级公式适合放推导：

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

再来一个稍微长一点的例子：

f(x)=∑n=0∞f(n)(a)n!(x−a)nf(x) = \sum_{n=0}^{\infty} \frac{f^{(n)}(a)}{n!}(x-a)^n

Mermaid 图表

下面是一张流程图。它从普通 mermaid 代码块渲染出来，不需要手写 SVG。

flowchart LR
  A[写下 MDX] --> B[Astro 内容集合]
  B --> C[Markdown 增强管线]
  C --> D[文章页面]
  D --> E[读者阅读]

时序图也可以写：

sequenceDiagram
  participant Writer as 写作者
  participant Blog as 博客
  participant Reader as 读者
  Writer->>Blog: 提交 MDX 文章
  Blog->>Blog: 渲染公式、图表和组件
  Reader->>Blog: 打开文章
  Blog-->>Reader: 返回完整阅读页面

提示框

提示框使用 remark-directive 的容器语法，写起来接近 Firefly。

:::note title=“普通说明” 适合补充背景信息，不打断正文节奏。 :::

:::tip title=“写作建议” 如果一段内容可以帮助读者少走弯路，就适合放进提示框。 :::

:::warning title=“注意事项” 外部 iframe 和 GitHub 数据都依赖第三方服务，可访问性会受到网络环境影响。 :::

:::danger title=“危险操作” 不要把密码、Token、私有链接、后台截图或未处理的原始照片写进公开文章。 :::

GitHub 仓库卡片

GitHub 卡片用于在文章中引用项目。它会先展示基础信息，再在浏览器里尝试读取 GitHub API 补全 stars、forks 和语言。

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

也可以手写标题和描述，用于网络不可用时保持良好展示：

mermaid-js/mermaid 用文本语法生成流程图、时序图、甘特图等图表。 Repository Stars -- Forks --

iframe 嵌入

iframe 用封装组件输出，默认带懒加载、标题和响应式比例。

Astro 官方网站

剧透和折叠内容

当正文里有答案、补充解释或较长内容时，可以用折叠块。

展开查看一个隐藏说明

这里是折叠内容。它默认不会占用太多注意力，但读者想深入时可以主动展开。

展开查看一个小结

这个折叠块默认展开，用来展示 open 属性的效果。

代码块增强

普通代码块仍然支持语言标签和复制按钮：

type WritingFeature = {
  name: string;
  enabled: boolean;
};


const features: WritingFeature[] = [
  { name: "math", enabled: true },
  { name: "mermaid", enabled: true },
  { name: "callout", enabled: true },
];


console.log(features.filter((feature) => feature.enabled));

没有标注语言时，文章页也会尝试推断：

const message = "hello enhanced writing";
console.log(message);

一次性检查清单

如果这篇文章里每个小节都正常显示，说明下面这些能力都已经就位：

  • 数学公式渲染。
  • Mermaid 图表渲染。
  • :::note、:::tip、:::warning、:::danger 提示框。
  • GitHub 仓库卡片。
  • iframe 响应式嵌入。
  • 剧透和折叠内容。
  • 代码块语言标签和复制按钮。

这就是当前博客的增强写作基线。以后新增更多写作组件时，也可以继续把示例补到这篇文章里。