Markdown 写作

标题锚点、GFM 表格、代码高亮、Callout、Mermaid 与安全边界。

Tomz Dang约 2 分钟

Folio 的正文使用 Markdown 编写。React 阅读页与静态输出共用同一个 renderFolioMarkdown() 渲染器，因此开发预览、线上页面与静态 HTML 的排版结果一致。

tip 先写结论，再补细节。 :::

Callout 正文本身支持 Markdown；它适合补充说明与风险提示，不应替代正文结构。

Mermaid#

```mermaid
flowchart LR
  A[Markdown] --> B[Folio engine]
  B --> C[Semantic HTML]
  C --> D[设计系统]
```

Mermaid 是渐进增强：HTML 中始终先保留可读源码，浏览器加载 Mermaid 成功后再替换为 SVG。渲染失败时不会吞掉内容。

原始 HTML#

需要嵌入图表、视频或站点组件时，可以直接写 HTML，或使用 ::: html 块：

::: html
<figure class="site-figure">
  <img src="/images/example.png" alt="示例" />
  <figcaption>由站点样式负责排版。</figcaption>
</figure>
:::

原始 HTML 原样输出，适合可信仓库内容，不适合用户投稿。

渲染入口与选项#

React 阅读页：

import { FolioMarkdown } from "@uichat-mira/folio";

<FolioMarkdown source={doc.body} options={{ removeH1: true }} />;

静态构建或自定义输出：

import { renderFolioMarkdown } from "@uichat-mira/folio";

const html = renderFolioMarkdown(doc.body, {
  removeH1: true,
  headingAnchors: true,
});
  • removeH1 去掉正文里重复的一级标题；Folio 的阅读布局默认开启。
  • headingAnchors 为 h2–h4 生成锚点与目录链接，默认开启。

失败语义#

Mermaid 渲染失败时保留源码，不会留下空白区域；内容错误应在上线前通过构建与人工检查发现。

相关文档#