这块博客能写点什么花样

这块博客的写作系统支持一些超出普通 Markdown 的东西。这篇文章把它们逐个演示一遍—— 你既能当它是效果预览,也能当它是一份"抄作业"的模板。写法细节见仓库里的 docs/BLOG_AUTHORING.md。

提示卡:七种语气

用 :::类型标题 开一个提示卡,内部支持任意 Markdown。

普通提示

最常用的一种。可以放加粗、代码、链接。

小技巧

不写标题时,标题栏会用类型名兜底。

成功

用来标记"这样做是对的"。

注意

容易踩坑的地方放这里。

危险

不可逆操作、安全风险,用最强的语气。

引用

也可以在里面继续嵌套普通的引用块。

折叠:把细节藏起来

冗长的推导、可选的旁支,用 :::details 折叠,默认收起,点击展开。

点开看一段被折叠的推导

这里可以放任何东西,包括列表和代码:

第一步
第二步

def collapse_me():
    return "你现在看到我了"

标签页:同一件事的多个版本

:::tabs 配合 === 面板名,最适合"同一段逻辑的多语言实现"。

def fib(n):
    a, b = 0, 1
    for _ in range(n):
        a, b = b, a + b
    return a

function fib(n) {
  let [a, b] = [0, 1];
  for (let i = 0; i < n; i++) [a, b] = [b, a + b];
  return a;
}

第三个面板放普通文字。第一个面板默认激活,点上面的标签切换。

数学公式:构建期 KaTeX

行内公式像这样:当 $a \ne 0$ 时,方程 $ax^2 + bx + c = 0$ 的解为 $x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$ 。

块级公式独占一行,居中展示:

\int_{-\infty}^{\infty} e^{-x^2}\,dx = \sqrt{\pi}

\mathbf{A}\mathbf{x} = \lambda\mathbf{x} \quad\Longrightarrow\quad \det(\mathbf{A} - \lambda\mathbf{I}) = 0

公式在构建期就渲染成 HTML,首屏即完整,不依赖运行时脚本。

Mermaid:让流程"画"出来

用 ```mermaid 代码块写图,客户端按需渲染(只有含图的页面才加载 Mermaid)。

一个流程图:

flowchart LR
    A[写 Markdown] --> B{有增强语法?}
    B -->|没有| C[普通渲染]
    B -->|有| D[marked 扩展]
    D --> E[构建期出 HTML]
    C --> E
    E --> F[BlogEnhancer 客户端增强]
    F --> G([读者看到成品])

一个时序图:

sequenceDiagram
    participant 读者
    participant 页面
    participant iframe as 沙箱嵌入
    读者->>页面: 打开文章
    页面->>iframe: srcdoc 注入内容
    iframe-->>页面: postMessage(高度)
    页面->>页面: 自适应 iframe 高度
    读者->>iframe: 点击交互
    Note over iframe: 脚本被沙箱关住,<br/>碰不到主页面

可交互嵌入:sandbox iframe

这是"安全塞进任意 HTML/CSS/JS"的正解。下面是一个真正能点的小计数器 —— 它的样式和脚本都被关在沙箱里,既污染不了文章,也访问不到主页面。

再来一个纯 Canvas 的小动画,证明脚本、动画、requestAnimationFrame 都能跑:

顺带:这些基础也一直在

代码块自动高亮,右上角有语言标签和复制按钮:

fn main() {
    let msg = "复制我试试 →";
    println!("{msg}");
}

表格、引用照常:

特性	何时渲染	依赖
提示卡 / 折叠 / 标签页	构建期	无
数学公式	构建期(KaTeX)	katex
Mermaid 图表	客户端懒加载	mermaid
沙箱嵌入	构建期包壳 + 客户端自适应	无

右上角(超宽屏)会有一个自动生成的目录,随滚动高亮当前小节;顶部还有一条阅读进度条。

小结

普通 Markdown 负责"说清楚",这些增强负责"演出来"。别滥用——能用一句话讲明白的,就别画图。

— 姜睦然