mobile wallpaper 1mobile wallpaper 2mobile wallpaper 3mobile wallpaper 4mobile wallpaper 5mobile wallpaper 6mobile wallpaper 7mobile wallpaper 8mobile wallpaper 9mobile wallpaper 10mobile wallpaper 11mobile wallpaper 12mobile wallpaper 13mobile wallpaper 14mobile wallpaper 15mobile wallpaper 16mobile wallpaper 17mobile wallpaper 18mobile wallpaper 19mobile wallpaper 20mobile wallpaper 21
2564 字
7 分钟
浏览量 --
渲染 Markdown 文章语法使用示例

这篇文章不是一次性的演示页,而是后面长期维护的 Markdown 扩展语法示例集合。

以后博客里只要新增了新的 Markdown 渲染能力,我都会继续补到这里,方便自己统一查看,也方便后面排查“语法有没有正常渲染”“样式有没有被改坏”这类问题。

这篇文章的用途

这里更像一份持续更新的语法清单。

后面如果扩展了新的 Markdown 能力,比如新的卡片、新的提示块、新的内容组件或者别的自定义指令,都可以继续直接往下追加。

通用网站卡片#

适合在文章里直接展示一个普通网站链接,不只是纯文本链接,而是自动解析成卡片。

语法#

::site{url="https://waline.js.org/"}

效果#

Waline logoWalinewaline.js.org一款简洁、安全的评论系统。https://waline.js.org/

如果写的是不带协议头的网址,也可以正常使用:

::site{url="ynga.kingcola-icg.cn"}
HiYngaの随记 logoHiYngaの随记ynga.kingcola-icg.cnHiYngaの随记 - 把路过的风景🎐、零碎的心事🌸慢慢收集起来,写成属于自己的小记📖🌷https://ynga.kingcola-icg.cn/

如果目标站点本身没有做好 SEO 元数据,也可以手动覆盖卡片信息:

::site{url="https://t.alcy.cc/" title="栗次元API-举个栗子" description="分享二次元、壁纸、原神、风景、横竖图等随机图片接口与图源服务。" accent="#7c5cff"}

目前网站卡片会优先解析这些信息:

  • og:site_name / og:title
  • og:description / meta[name="description"]
  • og:image / twitter:image
  • apple-touch-icon / icon / shortcut icon

如果这些都没有,会继续回退尝试:

  • 页面 <title>
  • meta[name="keywords"]
  • 页面正文里的首张同源图片

效果#

栗次元API-举个栗子 logo栗次元API-举个栗子t.alcy.cc分享二次元、壁纸、原神、风景、横竖图等随机图片接口与图源服务。https://t.alcy.cc/

GitHub 仓库卡片#

适合在文章里展示 GitHub 项目仓库信息。

语法#

::github{repo="matsuzaka-yuki/Mizuki"}

效果#

matsuzaka-yuki
/
Mizuki
Waiting for api.github.com...
00K
0K
0K
Waiting...

Gitee 仓库卡片#

适合在文章里展示 Gitee 项目仓库信息,使用方式和 GitHub 卡片基本一致。

语法#

::gitee{repo="yngang/kingcola-icg-blog-web"}

效果#

yngang
/
kingcola-icg-blog-web
Waiting for gitee.com/api/v5/repos...
00K
0K
no-license
Waiting...

图片画廊网格#

适合把多张图片放在同一组里并排展示,效果和 Firefly[grid] ... [/grid] 基本一致并做了进一步的扩展实现。

CuteLeaf
/
Firefly
Waiting for api.github.com...
00K
0K
0K
Waiting...
  • 会根据包裹的图片数量自动布局,最多一行 4 张
  • 也支持手动指定行数、列数,以及逐行布局
  • 也支持按设备单独控制显示,比如只在桌面、只在平板、只在手机出现
  • 同一排图片会自动做等高铺满
  • 比例不一致时会用居中裁切补齐
  • 图注会保持底部对齐
  • 点击图片仍然可以走现有灯箱预览看完整图

基本语法#

[grid]
![示例图片一](./1.webp)
![示例图片二](./2.webp)
![示例图片三](./3.webp)
[/grid]

带图注示例#

[grid]
![网站首页预览](./1.webp "网站首页预览")
![文章详情预览](./2.webp "文章详情预览")
![图表渲染预览](./3.webp "图表渲染预览")
[/grid]

多行多列#

如果你想明确控制每行列数,而不是完全交给系统自动判断,也可以直接指定列数。比如下面这个写法会固定按 2 列布局,图片多了以后就自动换成多行多列:

[grid cols=2]
![网站首页预览](./1.webp "网站首页预览")
![文章详情预览](./2.webp "文章详情预览")
![图表渲染预览](./3.webp "图表渲染预览")
![再次展示一张图](./1.webp "再次展示一张图")
[/grid]

如果你希望进一步明确控制“总行数 + 总列数”,也可以写:

[grid rows=2 cols=3]
![图1](./1.webp "图1")
![图2](./2.webp "图2")
![图3](./3.webp "图3")
![图4](./4.webp "图4")
![图5](./1.webp "图5")
![图6](./2.webp "图6")
[/grid]

如果你要的是更精确的逐行排版,也支持直接指定每一行几张图:

[grid layout="4,3,2,1"]
![图1](./1.webp "图1")
![图2](./2.webp "图2")
![图3](./3.webp "图3")
![图4](./4.webp "图4")
![图5](./1.webp "图5")
![图6](./2.webp "图6")
![图7](./3.webp "图7")
![图8](./1.webp "图8")
![图9](./4.webp "图9")
![图10](./4.webp "图10")
[/grid]

如果你还想控制图片之间的间距,现在也支持:

[grid cols=3 gap=lg]
![图1](./1.webp "图1")
![图2](./2.webp "图2")
![图3](./3.webp "图3")
[/grid]

其中 gap=sm|md|lg 可以控制网格间距。

现在也支持响应式列数控制和设备可见性控制,比如:

[grid cols=4 desktop=true tablet=true tabletCols=3 mobile=true mobileCols=2]
![图一](./1.webp "图一")
![图二](./2.webp "图二")
![图三](./3.webp "图三")
![图四](./4.webp "图四")
[/grid]

这样桌面端会按 4 列显示,平板按 3 列显示,手机按 2 列显示。 如果某个设备不想显示,把对应开关设成 false 就行。

新增语法说明#

  • desktop=true|false 控制桌面端是否显示
  • tablet=true|false 控制平板端是否显示
  • mobile=true|false 控制手机端是否显示
  • tabletCols=1~3 控制平板端每行列数
  • mobileCols=1~2 控制手机端每行列数
  • 这些显示开关如果不写,默认都按 true 处理,也就是桌面、平板、手机都会显示

一般建议这样理解:

  • cols 是桌面端默认列数
  • tabletColsmobileCols 是单独给平板和手机准备的列数
  • layout="4,3,2,1" 还是可以继续用来做逐行排版
  • desktop / tablet / mobile 不写时,等价于都开启
  • 如果某个设备开关是 false,那一整组网格在这个设备上就不会显示

效果#

网站首页预览
文章详情预览
图表渲染预览
网站首页预览
文章详情预览
图表渲染预览
再次展示一张图

仅桌面端显示#

图一
图二
图三
图四

仅平板端显示#

图一
图二
图三

仅手机端显示#

图一
图二
图三
图四

两行每行三张图#

图一
图二
图三
图四
图五
图六

更自由的逐行排版(桌面端)#

图一
图二
图三
图四
图五
图六
图七
图八
图九
图十

更自由的逐行排版(平板端)#

图一
图二
图三
图五
图六
图十

更自由的逐行排版(移动端)#

图一
图二
图三

间距控制示例#

图一
图二
图三

响应式列数示例#

图一
图二
图三
图四

提示块#

适合用来强调说明、补充提醒或者做信息分区。

语法#

::::note[说明]
这里是一段补充说明内容。
::::
::::warning[提醒]
这里是一段提醒内容。
::::

效果#

说明

这里是一段补充说明内容。

提醒

这里是一段提醒内容。

数学公式#

适合在文章里写行内公式和块级公式。

行内公式 (Inline)#

行内公式使用单个 $ 符号包裹。

例如:欧拉公式 eiπ+1=0e^{i\pi} + 1 = 0 是数学中最优美的公式之一。

质能方程 E=mc2E = mc^2 也是家喻户晓。

块级公式 (Block)#

块级公式使用两个 $$ 符号包裹,会居中显示。

ex2dx=π\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}x=b±b24ac2ax = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}

复杂示例#

矩阵 (Matrices)#

(abcd)(αβγδ)=(aα+bγaβ+bδcα+dγcβ+dδ)\begin{pmatrix} a & b \\ c & d \end{pmatrix} \begin{pmatrix} \alpha & \beta \\ \gamma & \delta \end{pmatrix} = \begin{pmatrix} a\alpha + b\gamma & a\beta + b\delta \\ c\alpha + d\gamma & c\beta + d\delta \end{pmatrix}

极限与求和 (Limits and Sums)#

n=11n2=π26\sum_{n=1}^{\infty} \frac{1}{n^2} = \frac{\pi^2}{6}limx0sinxx=1\lim_{x \to 0} \frac{\sin x}{x} = 1

麦克斯韦方程组 (Maxwell’s Equations)#

E=ρε0B=0×E=Bt×B=μ0J+μ0ε0Et\begin{aligned} \nabla \cdot \mathbf{E} &= \frac{\rho}{\varepsilon_0} \\ \nabla \cdot \mathbf{B} &= 0 \\ \nabla \times \mathbf{E} &= -\frac{\partial \mathbf{B}}{\partial t} \\ \nabla \times \mathbf{B} &= \mu_0\mathbf{J} + \mu_0\varepsilon_0\frac{\partial \mathbf{E}}{\partial t} \end{aligned}

化学方程式 (Chemical Equations)#

CHX4+2OX2COX2+2HX2O\ce{CH4 + 2O2 -> CO2 + 2H2O}2HX2+OX2点燃2HX2O\ce{2H2 + O2 ->[\text{点燃}] 2H2O}

化学计量与单位 (Chemistry Units)#

1.23104 Jmol1\pu{1.23e4 J.mol^{-1}}5.0103 molL1\pu{5.0e-3 mol.L^{-1}}

分段函数 (Cases)#

f(x)={x2,x0x,x<0f(x)= \begin{cases} x^2, & x \ge 0 \\ -x, & x < 0 \end{cases}

盒装公式 (Boxed Formula)#

E=mc2\boxed{E = mc^2}

对齐推导 (Aligned Derivation)#

(×F)=001x2dx=13\begin{aligned} \nabla \cdot (\nabla \times \bm{F}) &= 0 \\ \int_0^1 x^2 \,\d x &= \frac{1}{3} \end{aligned}

数组与增广矩阵 (Array / Augmented Matrix)#

[125314]\left[ \begin{array}{cc|c} 1 & 2 & 5 \\ 3 & -1 & 4 \end{array} \right]

约分与删除线 (Cancel)#

x(x+1)x=x+1\frac{\cancel{x}\,(x+1)}{\cancel{x}} = x+1

宏命令示例 (Custom Macros)#

x=arg minxR(x2)2=2\begin{aligned} x^\star &= \argmin_{x \in \RR} (x-2)^2 \\ &= 2 \end{aligned}E[X]=ixipi,Var(X)=E[(XE[X])2]\E[X] = \sum_i x_i p_i, \qquad \Var(X) = \E[(X - \E[X])^2]Cov(X,Y)=E[(XE[X])(YE[Y])]\Cov(X, Y) = \E[(X - \E[X])(Y - \E[Y])]x2=x,x,x2x2\norm{\bm{x}}_2 = \sqrt{\inner{\bm{x}}{\bm{x}}}, \qquad \abs{x-2} \le \norm{\bm{x}}_2fx=2x,2fx2=2\pd{f}{x} = 2x, \qquad \pdd{f}{x} = 2

颜色与文本标签 (Color / Text)#

Gitee Red+Link Blue\color{#c71d23}{\text{Gitee Red}} \quad + \quad \color{#2563eb}{\text{Link Blue}}重点提示通过\textcolor{#d97706}{\text{重点提示}} \quad \textcolor{#16a34a}{\text{通过}}
x=arg minxR(x2)2(Opt-1)\tag{Opt-1} x^\star = \argmin_{x \in \RR} (x-2)^2KaTeX Supported Functionshttps://katex.org/docs/options\href{https://katex.org/docs/supported.html}{\text{KaTeX Supported Functions}} \quad\mid\quad \url{https://katex.org/docs/options}

受控 HTML 扩展 (Trusted HTML Extensions)#

HTML Class Enabled\htmlClass{math-accent}{\boxed{\text{HTML Class Enabled}}}这是一个受控样式标签\htmlClass{math-note}{\text{这是一个受控样式标签}}HTML Style Enabled\htmlStyle{color:var(--primary); background-color:var(--btn-plain-bg-hover); border-radius:.5rem; padding-inline:.45rem; padding-block:.12rem;}{\text{HTML Style Enabled}}

论文风格排版示例 (Paper-style Layout)#

L(θ)=1Ni=1N(fθ(xi),yi)+λθ22Empirical Risk with 2 Regularization(1)\begin{aligned} \mathcal{L}(\theta) &= \frac{1}{N}\sum_{i=1}^{N} \ell\bigl(f_\theta(x_i), y_i\bigr) + \lambda \norm{\theta}_2^2 \\ &\tag{1} \text{Empirical Risk with } \ell_2 \text{ Regularization} \end{aligned}p(xy=k)=1(2π)d/2det(Σk)1/2exp(12(xμk)TΣk1(xμk))\begin{aligned} p(\boldsymbol{x} \mid y = k) = \frac{1}{(2\pi)^{d/2}\operatorname{det}(\Sigma_k)^{1/2}} \exp\left( -\frac{1}{2}(\boldsymbol{x} - \mu_k)^{\mathsf{T}} \Sigma_k^{-1} (\boldsymbol{x} - \mu_k) \right) \end{aligned}

论文风格统一排版#

适合把常用公式整理成更像论文笔记的阅读结构,而不是只把一堆公式连续往下堆。

单行紧凑公式#

::::math-compact[单行紧凑公式]
$$
\operatorname{softmax}(\boldsymbol{z})_i
= \frac{e^{z_i}}{\sum_{j=1}^{K} e^{z_j}}
$$
::::
单行紧凑公式
softmax(z)i=ezij=1Kezj\operatorname{softmax}(\boldsymbol{z})_i = \frac{e^{z_i}}{\sum_{j=1}^{K} e^{z_j}}

双栏并排公式#

::::math-cols[双栏并排公式]
:::math-col[损失函数]
$$
\mathcal{L}_{\mathrm{CE}}
= - \sum_{k=1}^{K} y_k \log \hat{y}_k
$$
:::
:::math-col[预测规则]
$$
\hat{y}
= \argmax_{k \in \set{1,\dots,K}} p_\theta(y=k \mid \boldsymbol{x})
$$
:::
::::
双栏并排公式
损失函数
LCE=k=1Kyklogy^k\mathcal{L}_{\mathrm{CE}} = - \sum_{k=1}^{K} y_k \log \hat{y}_k
预测规则
y^=arg maxk{1,,K}pθ(y=kx)\hat{y} = \argmax_{k \in \set{1,\dots,K}} p_\theta(y=k \mid \boldsymbol{x})

带编号定理 / 引理风格#

::::theorem[一阶最优性条件]
若函数 $f$ 在 $x^\star$ 处可微,且 $x^\star$ 是无约束局部极小点,则
$$
\nabla f(x^\star) = 0
$$
::::
::::lemma[均值向量的线性性]
若随机向量 $\boldsymbol{X}, \boldsymbol{Y}$ 具有有限期望,且 $a,b \in \RR$,则
$$
\mathbb{E}[a\boldsymbol{X} + b\boldsymbol{Y}]
= a\,\mathbb{E}[\boldsymbol{X}] + b\,\mathbb{E}[\boldsymbol{Y}]
$$
::::
一阶最优性条件

若函数 ffxx^\star 处可微,且 xx^\star 是无约束局部极小点,则

f(x)=0\nabla f(x^\star) = 0
均值向量的线性性

若随机向量 X,Y\boldsymbol{X}, \boldsymbol{Y} 具有有限期望,且 a,bRa,b \in \RR,则

E[aX+bY]=aE[X]+bE[Y]\mathbb{E}[a\boldsymbol{X} + b\boldsymbol{Y}] = a\,\mathbb{E}[\boldsymbol{X}] + b\,\mathbb{E}[\boldsymbol{Y}]

长公式单行滚动#

长公式保持单行展示并支持左右滚动,这样更接近论文排版,也不会被强行拆成多行。

::::math-long[长公式单行滚动]
$$
\operatorname{KL}\!\bigl(q_\phi(\boldsymbol{z}\mid\boldsymbol{x}) \,\|\, p(\boldsymbol{z})\bigr)
- \mathbb{E}_{q_\phi(\boldsymbol{z}\mid\boldsymbol{x})}\!\left[\log p_\theta(\boldsymbol{x}\mid\boldsymbol{z})\right]
+ \lambda \sum_{l=1}^{L} \left\lVert \mathbf{W}^{(l)} \right\rVert_F^2
+ \beta \sum_{i=1}^{N}\sum_{k=1}^{K} y_{ik}\log\frac{y_{ik}}{\hat{y}_{ik}}
$$
::::
长公式单行滚动
KL ⁣(qϕ(zx)p(z))Eqϕ(zx) ⁣[logpθ(xz)]+λl=1LW(l)F2+βi=1Nk=1Kyiklogyiky^ik\operatorname{KL}\!\bigl(q_\phi(\boldsymbol{z}\mid\boldsymbol{x}) \,\|\, p(\boldsymbol{z})\bigr) - \mathbb{E}_{q_\phi(\boldsymbol{z}\mid\boldsymbol{x})}\!\left[\log p_\theta(\boldsymbol{x}\mid\boldsymbol{z})\right] + \lambda \sum_{l=1}^{L} \left\lVert \mathbf{W}^{(l)} \right\rVert_F^2 + \beta \sum_{i=1}^{N}\sum_{k=1}^{K} y_{ik}\log\frac{y_{ik}}{\hat{y}_{ik}}

机器学习常用模板#

softmax(z)i=ezij=1Kezj,y^=arg maxk{1,,K}pθ(y=kx)\operatorname{softmax}(\boldsymbol{z})_i = \frac{e^{z_i}}{\sum_{j=1}^{K} e^{z_j}}, \qquad \hat{y} = \argmax_{k \in \set{1,\dots,K}} p_\theta(y=k \mid \boldsymbol{x})LCE=k=1Kyklogy^k,KL(pq)=xp(x)logp(x)q(x)\mathcal{L}_{\mathrm{CE}} = - \sum_{k=1}^{K} y_k \log \hat{y}_k, \qquad \operatorname{KL}\bigl(p \,\|\, q\bigr) = \sum_x p(x)\log\frac{p(x)}{q(x)}

线性代数常用模板#

ARm×n,rank(A)min(m,n),tr(ATA)=AF2\mathbf{A} \in \RR^{m \times n}, \qquad \operatorname{rank}(\mathbf{A}) \le \min(m, n), \qquad \operatorname{tr}(\mathbf{A}^{\mathsf{T}} \mathbf{A}) = \norm{\mathbf{A}}_F^2diag(λ1,,λn)=(λ1000λ2000λn)\operatorname{diag}(\lambda_1, \dots, \lambda_n) = \begin{pmatrix} \lambda_1 & 0 & \cdots & 0 \\ 0 & \lambda_2 & \cdots & 0 \\ \vdots & \vdots & \ddots & \vdots \\ 0 & 0 & \cdots & \lambda_n \end{pmatrix}

概率统计常用模板#

X1,,Xni.i.d.N(μ,σ2),Xˉ=1ni=1nXiX_1, \dots, X_n \overset{\mathrm{i.i.d.}}{\sim} \mathcal{N}(\mu, \sigma^2), \qquad \bar{X} = \frac{1}{n}\sum_{i=1}^{n} X_iE[XY]=xxp(xY),Var(X)=E[X2]E[X]2\E[X \mid Y] = \sum_x x \, p(x \mid Y), \qquad \Var(X) = \E[X^2] - \E[X]^2

优化问题常用模板#

minxRnf(x)s.t.gi(x)0,i=1,,mhj(x)=0,j=1,,p\begin{aligned} \min_{\boldsymbol{x} \in \RR^n}\quad & f(\boldsymbol{x}) \\ \text{s.t.}\quad & g_i(\boldsymbol{x}) \le 0,\quad i=1,\dots,m \\ & h_j(\boldsymbol{x}) = 0,\quad j=1,\dots,p \end{aligned}x(t+1)=x(t)ηtf(x(t)),df(x)dxx=x=0\boldsymbol{x}^{(t+1)} = \boldsymbol{x}^{(t)} - \eta_t \grad f\bigl(\boldsymbol{x}^{(t)}\bigr), \qquad \frac{\mathrm{d} f(x)}{\mathrm{d} x} \bigg\rvert_{x=x^\star} = 0

更多 KaTeX 语法请参考 KaTeX Supported Functions

Mermaid 图表#

适合在文章里快速插入流程图之类的结构化内容。

现在这套 Mermaid 展示会优先渲染当前可见区域里的图表,正文里默认使用固定预览视口,长图不会再直接把整段文章撑裂。

  • 支持拖拽查看
  • 支持滚轮缩放
  • 支持双击快速放大 / 重置
  • 支持统一风格的全屏预览

流程图示例#

流程图非常适合表示流程或算法步骤。

Mermaid 图表加载中...

时序图示例#

时序图显示对象之间随时间的交互。

Mermaid 图表加载中...

甘特图示例#

甘特图非常适合显示项目进度和时间线。

Mermaid 图表加载中...

类图示例#

类图显示系统的静态结构,包括类、属性、方法及其关系。

Mermaid 图表加载中...

状态图示例#

状态图显示对象在其生命周期中经历的状态序列。

Mermaid 图表加载中...

饼图示例#

饼图非常适合显示比例和百分比数据。

Mermaid 图表加载中...

ER 图示例#

ER 图适合描述实体关系和字段结构。

Mermaid 图表加载中...

用户旅程图示例#

Journey 图适合梳理一段用户体验流程。

Mermaid 图表加载中...

Git Graph 示例#

Git Graph 非常适合表示分支和提交关系。

Mermaid 图表加载中...

PlantUML 图表#

适合在文章里写时序图、活动图、状态图、组件图、部署图、ER 图这类工程文档常见图表。

这次博客里的接入方式直接沿用了 Firefly 的实现:

CuteLeaf
/
Firefly
Waiting for api.github.com...
00K
0K
0K
Waiting...
  • Markdown 里使用 plantuml 代码块
  • 也支持 pumluml 作为代码块语言别名
  • 构建阶段自动把源码编码成 PlantUML Server 的 SVG 地址
  • 页面端根据明暗主题自动切换图源
  • 同时支持缩放、拖拽、双击放大、全屏查看、显示源码、复制源码、在新标签打开原图和失败重试

最小语法#

```plantuml
@startuml
Alice -> Bob: Hello
Bob --> Alice: Hi
@enduml
```
```puml
@startuml
Alice -> Bob: Alias works
@enduml
```
```uml
@startuml
Bob -> Alice: Alias works too
@enduml
```

最小效果#

PlantUML 图表加载中...
@startuml
Alice -> Bob: Hello
Bob --> Alice: Hi
@enduml

活动图示例#

PlantUML 图表加载中...
@startuml
start
:用户提交订单;
if (库存充足?) then (是)
  :冻结库存;
  :创建支付单;
  if (支付成功?) then (是)
    :生成发货单;
    :通知仓库拣货;
  else (否)
    :取消订单;
    :释放库存;
  endif
else (否)
  :提示缺货;
endif
stop
@enduml

状态图示例#

PlantUML 图表加载中...
@startuml
[*] --> 草稿

草稿 --> 待审核 : 提交
待审核 --> 草稿 : 驳回
待审核 --> 已发布 : 审核通过
已发布 --> 已归档 : 到期归档
已发布 --> 草稿 : 撤回修改

state 已发布 {
  [*] --> 可见
  可见 --> 隐藏 : 手动隐藏
  隐藏 --> 可见 : 恢复展示
}

已归档 --> [*]
@enduml

用例图示例#

PlantUML 图表加载中...
@startuml
left to right direction
actor 游客
actor 用户
actor 管理员

rectangle 博客系统 {
  usecase "浏览文章" as UC1
  usecase "搜索内容" as UC2
  usecase "发表评论" as UC3
  usecase "点赞收藏" as UC4
  usecase "审核评论" as UC5

组件图示例#

PlantUML 图表加载中...
@startuml
package "Mizuki Blog" {
  [Astro App] as App
  [Markdown Parser] as Parser
  [PlantUML Encoder] as Encoder
  [Theme Switcher] as Theme
  [Search Indexer] as Search
}

cloud "PlantUML Server"

部署图示例#

PlantUML 图表加载中...
@startuml
node "User Device" {
  artifact "Browser"
}

node "CDN / Edge" {
  artifact "Static Assets"
}

node "PlantUML Service" {
  artifact "SVG Renderer"
}

database "Markdown Content" {
  artifact

ER 图示例#

PlantUML 图表加载中...
@startuml
entity User {
  *id : uuid <<PK>>
  --
  username : varchar
  email : varchar
  created_at : datetime
}

entity Post {
  *id : uuid <<PK>>
  --
  author_id : uuid <<FK>>
  title : varchar

时序图示例#

PlantUML 图表加载中...
@startuml
autonumber
actor User as 用户
participant Web as 前端页面
participant API as 网关接口
participant Auth as 认证服务
database Redis as 会话缓存

用户 -> 前端页面 : 输入账号密码并提交
前端页面 -> 网关接口 : POST /login
网关接口 -> 认证服务 :

C4 容器图示例#

PlantUML 图表加载中...
@startuml
!include <C4/C4_Container>

Person(user, "博客访客", "阅读文章与搜索内容")

System_Boundary(system, "Mizuki Blog") {
  Container(web, "Web App", "Astro + Svelte", "渲染页面与交互")
  Container(content, "Content

类图示例#

PlantUML 图表加载中...
@startuml
class Post {
  +id: UUID
  +title: string
  +publishedAt: Date
  +render(): HTML
}

class MarkdownRenderer {
  +parse(source: string): AST
  +render(ast: AST): HTML
}

class PlantUMLRenderer

对象图示例#

PlantUML 图表加载中...
@startuml
object blog {
  title = "HiYnga Blog"
  theme = "Mizuki"
}

object post {
  slug = "website-make-demo"
  diagrams = 18
}

object renderer {
  server = "plantuml.com"
  darkTheme = "cyborg"
}

思维导图示例#

PlantUML 图表加载中...
@startmindmap
* 博客渲染能力
** Markdown 基础
*** 标题
*** 列表
*** 引用
** 增强语法
*** Mermaid
*** PlantUML
*** 数学公式
** 内容组件
*** GitHub 卡片
*** 网站卡片
*** 提示块
@endmindmap

WBS 工作分解图示例#

PlantUML 图表加载中...
@startwbs
* 网站搭建
** 内容系统
*** 文章集合
*** 分类标签
*** SEO 元信息
** 渲染能力
*** Mermaid
*** PlantUML
*** KaTeX
** 页面体验
*** 响应式布局
*** 暗色模式
*** 图片灯箱
@endwbs

Gantt 甘特图示例#

PlantUML 图表加载中...
@startgantt
title 博客功能迭代计划
[设计 Markdown 扩展] requires 3 days
[接入 PlantUML] requires 2 days
[接入 PlantUML] starts at [设计 Markdown 扩展]'s end
[补充示例文章] requires 2 days
[补充示例文章] starts at [接入 PlantUML]'s end

JSON 数据图示例#

PlantUML 图表加载中...
@startjson
{
  "site": "HiYnga Blog",
  "post": {
    "slug": "website-make-demo",
    "category": "网站搭建",
    "tags": ["Markdown", "PlantUML", "Mizuki"]
  },
  "features": {
    "mermaid": true,

YAML 数据图示例#

PlantUML 图表加载中...
@startyaml
site: HiYnga Blog
theme: Mizuki
post:
  slug: website-make-demo
  category: 网站搭建
  tags:
    - Markdown
    - PlantUML
    - Diagram
features:
  mermaid: true
  plantuml: true
  katex: true

Salt 线框图示例#

PlantUML 图表加载中...
@startsalt
{+
  {^文章编辑器}
  Title    | "Markdown PlantUML 图表示例      "
  Slug     | "website-make-demo               "
  Category | ^网站搭建^
  [X] 发布
  [ ] 置顶
  .
  [保存草稿] | [发布文章]
}
@endsalt

Timing 时序时间图示例#

PlantUML 图表加载中...
@startuml
concise "Author" as Author
concise "Renderer" as Renderer
concise "Browser" as Browser

Author is write
Renderer is idle
Browser is wait

@Author
0 is write
+20 is save
+20 is done

@Rendere

Chart 图表示例#

这个是 PlantUML 官方较新的能力。官方文档写的是从 1.2026.0 开始支持 @startchart。如果你后面看到这个示例没有渲染,通常是远端 PlantUML Server 版本没同步到对应能力。

PlantUML 图表加载中...
@startchart
h-axis [Mon, Tue, Wed, Thu, Fri]
v-axis "Posts" 0 --> 10
bar "Published" [1, 2, 1, 3, 2] #3498db labels
line "Drafts" [2, 1, 3, 2, 4] #ff7f0e labels
legend right
@endchart

Expressive Code 代码块#

代码块如何使用 Expressive Code 展示代码块。提供的示例基于官方文档,您可以参考以获取更多详细信息。

语法高亮#

语法高亮

常规语法高亮#

console.log('此代码有语法高亮!')

渲染 ANSI 转义序列#

Terminal window
Standard ANSI colors:
- Dimmed: Black Red Green Yellow Blue Magenta Cyan White
- Foreground: Black Red Green Yellow Blue Magenta Cyan White
- Background: Black Red Green Yellow Blue Magenta Cyan White
- Reversed: Black Red Green Yellow Blue Magenta Cyan White
8-bit colors (showing colors 160-171 as an example):
- Dimmed: 160 161 162 163 164 165 166 167 168 169 170 171
- Foreground: 160 161 162 163 164 165 166 167 168 169 170 171
- Background: 160 161 162 163 164 165 166 167 168 169 170 171
- Reversed: 160 161 162 163 164 165 166 167 168 169 170 171
24-bit colors (full RGB):
- Dimmed: ForestGreen - RGB(34,139,34) RebeccaPurple - RGB(102,51,153)
- Foreground: ForestGreen - RGB(34,139,34) RebeccaPurple - RGB(102,51,153)
- Background: ForestGreen - RGB(34,139,34) RebeccaPurple - RGB(102,51,153)
- Reversed: ForestGreen - RGB(34,139,34) RebeccaPurple - RGB(102,51,153)
Font styles:
- Default
- Bold
- Dimmed
- Italic
- Underline
- Reversed
- Strikethrough

编辑器和终端框架#

编辑器和终端框架

代码编辑器框架#

my-test-file.js
console.log('标题属性示例')

src/content/index.html
<div>文件名注释示例</div>

终端框架#

echo "此终端框架没有标题"

PowerShell 终端示例
Write-Output "这个有标题!"

覆盖框架类型#

echo "看,没有框架!"

PowerShell Profile.ps1
# 如果不覆盖,这将是一个终端框架
function Watch-Tail { Get-Content -Tail 20 -Wait $args }
New-Alias tail Watch-Tail

文本和行标记#

文本和行标记

标记整行和行范围#

// 第1行 - 通过行号定位
// 第2行
// 第3行
// 第4行 - 通过行号定位
// 第5行
// 第6行
// 第7行 - 通过范围 "7-8" 定位
// 第8行 - 通过范围 "7-8" 定位

选择行标记类型 (mark, ins, del)#

line-markers.js
function demo() {
console.log('此行标记为已删除')
// 此行和下一行标记为已插入
console.log('这是第二个插入行')
return '此行使用中性默认标记类型'
}

为行标记添加标签#

labeled-line-markers.jsx
<button
role="button"
{...props}
value={value}
className={buttonClassName}
disabled={disabled}
active={active}
>
{children &&
!active &&
(typeof children === 'string' ? <span>{children}</span> : children)}
</button>

在单独行上添加长标签#

labeled-line-markers.jsx
<button
role="button"
{...props}
value={value}
className={buttonClassName}
disabled={disabled}
active={active}
>
{children &&
!active &&
(typeof children === 'string' ? <span>{children}</span> : children)}
</button>

使用类似 diff 的语法#

此行将标记为已插入
此行将标记为已删除
这是常规行

--- a/README.md
+++ b/README.md
@@ -1,3 +1,4 @@
+this is an actual diff file
-all contents will remain unmodified
no whitespace will be removed either

结合语法高亮和类似 diff 的语法#

function thisIsJavaScript() {
// 整个块都会以 JavaScript 高亮显示,
// 并且我们仍然可以为其添加 diff 标记!
console.log('要删除的旧代码')
console.log('新的闪亮代码!')
}

标记行内的单独文本#

function demo() {
// 标记行内的任何给定文本
return '支持给定文本的多个匹配项';
}

正则表达式#

console.log('单词 yesyep 将被标记。')

转义正斜杠#

echo "Test" > /home/test.txt

选择内联标记类型 (mark, ins, del)#

function demo() {
console.log('这些是插入和删除的标记类型');
// return 语句使用默认标记类型
return true;
}

自动换行#

自动换行

为每个块配置自动换行#

// 启用换行的示例
function getLongString() {
return '这是一个非常长的字符串,除非容器极宽,否则很可能无法适应可用空间'
}

// wrap=false 的示例
function getLongString() {
return '这是一个非常长的字符串,除非容器极宽,否则很可能无法适应可用空间'
}

配置换行的缩进#

// preserveIndent 示例(默认启用)
function getLongString() {
return '这是一个非常长的字符串,除非容器极宽,否则很可能无法适应可用空间'
}

// preserveIndent=false 的示例
function getLongString() {
return '这是一个非常长的字符串,除非容器极宽,否则很可能无法适应可用空间'
}

可折叠部分#

可折叠部分

5 collapsed lines
// 所有这些样板设置代码将被折叠
import { someBoilerplateEngine } from '@example/some-boilerplate'
import { evenMoreBoilerplate } from '@example/even-more-boilerplate'
const engine = someBoilerplateEngine(evenMoreBoilerplate())
// 这部分代码默认可见
engine.doSomething(1, 2, 3, calcFn)
function calcFn() {
// 您可以有多个折叠部分
3 collapsed lines
const a = 1
const b = 2
const c = a + b
// 这将保持可见
console.log(`计算结果: ${a} + ${b} = ${c}`)
return c
}
4 collapsed lines
// 直到块末尾的所有代码将再次被折叠
engine.closeConnection()
engine.freeMemory()
engine.shutdown({ reason: '示例样板代码结束' })

行号#

行号

为每个块显示行号#

// 此代码块将显示行号
console.log('来自第2行的问候!')
console.log('我在第3行')

// 此块禁用行号
console.log('你好?')
console.log('抱歉,你知道我在第几行吗?')

更改起始行号#

console.log('来自第5行的问候!')
console.log('我在第6行')

后续补充#

这篇文章后面会继续追加新的 Markdown 扩展示例。

如果哪次改动把现有渲染效果改坏了,这篇文章也可以顺手拿来当回归检查页用。

分享

如果这篇文章对你有帮助,欢迎分享!

渲染 Markdown 文章语法使用示例
https://ynga.kingcola-icg.cn/posts/website-make-demo/
作者
HiYnga
发布于
2026-05-10
许可协议
CC BY-NC-SA 4.0

部分信息可能已经过时

文章评论
浏览量 --
评论数 --
相关文章 智能推荐
1
给博客做一个可以导出文章详情长图的功能
技术实践 记录我如何给博客加上文章详情下载能力,让主线程只负责分段截图,把 PNG 编码和压缩搬到 Web Worker,并同时支持高清长图和 PDF 文章导出。
2
Cloudflare RAG 与博客上下文深度融合实践:让 AI 真正知道用户现在在看什么
技术实践 记录我如何把博客前端上下文、结构化提问意图和 Cloudflare RAG 检索链路进一步打通,解决 AI 在文章详情页里经常“不知道用户在问什么”的问题。
3
博客 PWA → PakePlus → APP
网站搭建 记录一下我怎么在 Mizuki 静态博客上完善 PWA 能力,再进一步用 PakePlus 做一个手机桌面壳 APP。目标不是另起一套客户端,而是让博客在保留现有自动部署链路的前提下,拥有一个更稳定、更直接的手机访问入口。
4
用阿里云 ESA 给 Cloudflare-RAG 聊天页做一次国内加速
网站搭建 记录一下我怎么把部署在 Cloudflare Pages 上的 Cloudflare-RAG 聊天页,挂到阿里云 ESA 前面做国内访问加速。前面先用 pages.dev 直回源跑通,后面再换成单独的回源域名,把 Host、SNI 和 HTTPS 443 都对齐,整体会稳很多。
5
把 Cloudflare-RAG 真正接进 Mizuki 博客
AI 这一篇专门记录实现细节。包括我怎么把 Mizuki + Astro 的文章目录升级成 session 化 bundle,同步到 Cloudflare-RAG 的 Queue / Workflow / revision 链路,再通过 Edge Functions 和 Cloudflare Functions 做受保护的 embed token 分发与 session 鉴权,让 AI 对话只能被指定博客域名安全内嵌使用。

目录