当前页面没有目录
当前页面没有目录
这篇文章不是一次性的演示页,而是后面长期维护的 Markdown 扩展语法示例集合。
以后博客里只要新增了新的 Markdown 渲染能力,我都会继续补到这里,方便自己统一查看,也方便后面排查“语法有没有正常渲染”“样式有没有被改坏”这类问题。
这篇文章的用途这里更像一份持续更新的语法清单。
后面如果扩展了新的 Markdown 能力,比如新的卡片、新的提示块、新的内容组件或者别的自定义指令,都可以继续直接往下追加。
通用网站卡片#
适合在文章里直接展示一个普通网站链接,不只是纯文本链接,而是自动解析成卡片。
语法#
1::site{url="https://waline.js.org/"}效果#
如果写的是不带协议头的网址,也可以正常使用:
1::site{url="ynga.kingcola-icg.cn"}如果目标站点本身没有做好 SEO 元数据,也可以手动覆盖卡片信息:
1::site{url="https://t.alcy.cc/" title="栗次元API-举个栗子" description="分享二次元、壁纸、原神、风景、横竖图等随机图片接口与图源服务。" accent="#7c5cff"}目前网站卡片会优先解析这些信息:
og:site_name/og:titleog:description/meta[name="description"]og:image/twitter:imageapple-touch-icon/icon/shortcut icon
如果这些都没有,会继续回退尝试:
- 页面
<title> meta[name="keywords"]- 页面正文里的首张同源图片
效果#
GitHub 仓库卡片#
适合在文章里展示 GitHub 项目仓库信息。
语法#
1::github{repo="matsuzaka-yuki/Mizuki"}效果#
Gitee 仓库卡片#
适合在文章里展示 Gitee 项目仓库信息,使用方式和 GitHub 卡片基本一致。
语法#
1::gitee{repo="yngang/kingcola-icg-blog-web"}效果#
图片画廊网格#
适合把多张图片放在同一组里并排展示,效果和 Firefly 的 [grid] ... [/grid] 基本一致并做了进一步的扩展实现。
- 会根据包裹的图片数量自动布局,最多一行 4 张
- 也支持手动指定行数、列数,以及逐行布局
- 也支持按设备单独控制显示,比如只在桌面、只在平板、只在手机出现
- 同一排图片会自动做等高铺满
- 比例不一致时会用居中裁切补齐
- 图注会保持底部对齐
- 点击图片仍然可以走现有灯箱预览看完整图
基本语法#
1[grid]2345[/grid]带图注示例#
1[grid]2345[/grid]多行多列#
如果你想明确控制每行列数,而不是完全交给系统自动判断,也可以直接指定列数。比如下面这个写法会固定按 2 列布局,图片多了以后就自动换成多行多列:
1[grid cols=2]23456[/grid]如果你希望进一步明确控制“总行数 + 总列数”,也可以写:
1[grid rows=2 cols=3]2345678[/grid]如果你要的是更精确的逐行排版,也支持直接指定每一行几张图:
1[grid layout="4,3,2,1"]23456789101112[/grid]如果你还想控制图片之间的间距,现在也支持:
1[grid cols=3 gap=lg]2345[/grid]其中 gap=sm|md|lg 可以控制网格间距。
现在也支持响应式列数控制和设备可见性控制,比如:
1[grid cols=4 desktop=true tablet=true tabletCols=3 mobile=true mobileCols=2]23456[/grid]这样桌面端会按 4 列显示,平板按 3 列显示,手机按 2 列显示。
如果某个设备不想显示,把对应开关设成 false 就行。
新增语法说明#
desktop=true|false控制桌面端是否显示tablet=true|false控制平板端是否显示mobile=true|false控制手机端是否显示tabletCols=1~3控制平板端每行列数mobileCols=1~2控制手机端每行列数- 这些显示开关如果不写,默认都按
true处理,也就是桌面、平板、手机都会显示
一般建议这样理解:
cols是桌面端默认列数tabletCols和mobileCols是单独给平板和手机准备的列数layout="4,3,2,1"还是可以继续用来做逐行排版desktop/tablet/mobile不写时,等价于都开启- 如果某个设备开关是
false,那一整组网格在这个设备上就不会显示
效果#







仅桌面端显示#




仅平板端显示#



仅手机端显示#




两行每行三张图#






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










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






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



间距控制示例#



响应式列数示例#




提示块#
适合用来强调说明、补充提醒或者做信息分区。
语法#
1::::note[说明]2这里是一段补充说明内容。3::::4
5::::warning[提醒]6这里是一段提醒内容。7::::效果#
说明这里是一段补充说明内容。
提醒这里是一段提醒内容。
数学公式#
适合在文章里写行内公式和块级公式。
行内公式 (Inline)#
行内公式使用单个 $ 符号包裹。
例如:欧拉公式 eiπ+1=0 是数学中最优美的公式之一。
质能方程 E=mc2 也是家喻户晓。
块级公式 (Block)#
块级公式使用两个 $$ 符号包裹,会居中显示。
复杂示例#
矩阵 (Matrices)#
(acbd)(αγβδ)=(aα+bγcα+dγaβ+bδcβ+dδ)极限与求和 (Limits and Sums)#
n=1∑∞n21=6π2x→0limxsinx=1麦克斯韦方程组 (Maxwell’s Equations)#
∇⋅E∇⋅B∇×E∇×B=ε0ρ=0=−∂t∂B=μ0J+μ0ε0∂t∂E化学方程式 (Chemical Equations)#
CHX4+2OX2COX2+2HX2O2HX2+OX2点燃2HX2O化学计量与单位 (Chemistry Units)#
1.23⋅104 J⋅mol−15.0⋅10−3 mol⋅L−1分段函数 (Cases)#
f(x)={x2,−x,x≥0x<0盒装公式 (Boxed Formula)#
E=mc2对齐推导 (Aligned Derivation)#
∇⋅(∇×F)∫01x2dx=0=31数组与增广矩阵 (Array / Augmented Matrix)#
[132−154]约分与删除线 (Cancel)#
xx(x+1)=x+1宏命令示例 (Custom Macros)#
x⋆=x∈Rargmin(x−2)2=2E[X]=i∑xipi,Var(X)=E[(X−E[X])2]Cov(X,Y)=E[(X−E[X])(Y−E[Y])]∥x∥2=⟨x,x⟩,∣x−2∣≤∥x∥2∂x∂f=2x,∂x2∂2f=2颜色与文本标签 (Color / Text)#
Gitee Red+Link Blue重点提示通过公式编号与链接 (Tag / Link)#
x⋆=x∈Rargmin(x−2)2(Opt-1)KaTeX Supported Functions∣https://katex.org/docs/options受控 HTML 扩展 (Trusted HTML Extensions)#
HTML Class Enabled这是一个受控样式标签HTML Style Enabled论文风格排版示例 (Paper-style Layout)#
L(θ)=N1i=1∑Nℓ(fθ(xi),yi)+λ∥θ∥22Empirical Risk with ℓ2 Regularization(1)p(x∣y=k)=(2π)d/2det(Σk)1/21exp(−21(x−μk)TΣk−1(x−μk))论文风格统一排版#
适合把常用公式整理成更像论文笔记的阅读结构,而不是只把一堆公式连续往下堆。
单行紧凑公式#
1::::math-compact[单行紧凑公式]2$$3\operatorname{softmax}(\boldsymbol{z})_i4= \frac{e^{z_i}}{\sum_{j=1}^{K} e^{z_j}}5$$6::::双栏并排公式#
1::::math-cols[双栏并排公式]2:::math-col[损失函数]3$$4\mathcal{L}_{\mathrm{CE}}5= - \sum_{k=1}^{K} y_k \log \hat{y}_k6$$7:::8
9:::math-col[预测规则]10$$11\hat{y}12= \argmax_{k \in \set{1,\dots,K}} p_\theta(y=k \mid \boldsymbol{x})13$$14:::15::::带编号定理 / 引理风格#
1::::theorem[一阶最优性条件]2若函数 $f$ 在 $x^\star$ 处可微,且 $x^\star$ 是无约束局部极小点,则3
4$$5\nabla f(x^\star) = 06$$7::::8
9::::lemma[均值向量的线性性]10若随机向量 $\boldsymbol{X}, \boldsymbol{Y}$ 具有有限期望,且 $a,b \in \RR$,则11
12$$13\mathbb{E}[a\boldsymbol{X} + b\boldsymbol{Y}]14= a\,\mathbb{E}[\boldsymbol{X}] + b\,\mathbb{E}[\boldsymbol{Y}]15$$16::::若函数 f 在 x⋆ 处可微,且 x⋆ 是无约束局部极小点,则
∇f(x⋆)=0若随机向量 X,Y 具有有限期望,且 a,b∈R,则
E[aX+bY]=aE[X]+bE[Y]长公式单行滚动#
长公式保持单行展示并支持左右滚动,这样更接近论文排版,也不会被强行拆成多行。
1::::math-long[长公式单行滚动]2$$3\operatorname{KL}\!\bigl(q_\phi(\boldsymbol{z}\mid\boldsymbol{x}) \,\|\, p(\boldsymbol{z})\bigr)4- \mathbb{E}_{q_\phi(\boldsymbol{z}\mid\boldsymbol{x})}\!\left[\log p_\theta(\boldsymbol{x}\mid\boldsymbol{z})\right]5+ \lambda \sum_{l=1}^{L} \left\lVert \mathbf{W}^{(l)} \right\rVert_F^26+ \beta \sum_{i=1}^{N}\sum_{k=1}^{K} y_{ik}\log\frac{y_{ik}}{\hat{y}_{ik}}7$$8::::机器学习常用模板#
softmax(z)i=∑j=1Kezjezi,y^=k∈{1,…,K}argmaxpθ(y=k∣x)LCE=−k=1∑Kyklogy^k,KL(p∥q)=x∑p(x)logq(x)p(x)线性代数常用模板#
A∈Rm×n,rank(A)≤min(m,n),tr(ATA)=∥A∥F2diag(λ1,…,λn)=λ10⋮00λ2⋮0⋯⋯⋱⋯00⋮λn概率统计常用模板#
X1,…,Xn∼i.i.d.N(μ,σ2),Xˉ=n1i=1∑nXiE[X∣Y]=x∑xp(x∣Y),Var(X)=E[X2]−E[X]2优化问题常用模板#
x∈Rnmins.t.f(x)gi(x)≤0,i=1,…,mhj(x)=0,j=1,…,px(t+1)=x(t)−ηt∇f(x(t)),dxdf(x)x=x⋆=0更多 KaTeX 语法请参考 KaTeX Supported Functions。
Mermaid 图表#
适合在文章里快速插入流程图之类的结构化内容。
现在这套 Mermaid 展示会优先渲染当前可见区域里的图表,正文里默认使用固定预览视口,长图不会再直接把整段文章撑裂。
- 支持拖拽查看
- 支持滚轮缩放
- 支持双击快速放大 / 重置
- 支持统一风格的全屏预览
流程图示例#
流程图非常适合表示流程或算法步骤。
时序图示例#
时序图显示对象之间随时间的交互。
甘特图示例#
甘特图非常适合显示项目进度和时间线。
类图示例#
类图显示系统的静态结构,包括类、属性、方法及其关系。
状态图示例#
状态图显示对象在其生命周期中经历的状态序列。
饼图示例#
饼图非常适合显示比例和百分比数据。
ER 图示例#
ER 图适合描述实体关系和字段结构。
用户旅程图示例#
Journey 图适合梳理一段用户体验流程。
Git Graph 示例#
Git Graph 非常适合表示分支和提交关系。
PlantUML 图表#
适合在文章里写时序图、活动图、状态图、组件图、部署图、ER 图这类工程文档常见图表。
这次博客里的接入方式直接沿用了 Firefly 的实现:
- Markdown 里使用
plantuml代码块 - 也支持
puml和uml作为代码块语言别名 - 构建阶段自动把源码编码成 PlantUML Server 的 SVG 地址
- 页面端根据明暗主题自动切换图源
- 同时支持缩放、拖拽、双击放大、全屏查看、显示源码、复制源码、在新标签打开原图和失败重试
最小语法#
1```plantuml2@startuml3Alice -> Bob: Hello4Bob --> Alice: Hi5@enduml6```7
8```puml9@startuml10Alice -> Bob: Alias works11@enduml12```13
14```uml15@startuml16Bob -> Alice: Alias works too17@enduml18```最小效果#
活动图示例#
状态图示例#
用例图示例#
组件图示例#
部署图示例#
ER 图示例#
时序图示例#
C4 容器图示例#
类图示例#
对象图示例#
思维导图示例#
WBS 工作分解图示例#
Gantt 甘特图示例#
JSON 数据图示例#
YAML 数据图示例#
Salt 线框图示例#
Timing 时序时间图示例#
Chart 图表示例#
这个是 PlantUML 官方较新的能力。官方文档写的是从 1.2026.0 开始支持 @startchart。如果你后面看到这个示例没有渲染,通常是远端 PlantUML Server 版本没同步到对应能力。
Expressive Code 代码块#
代码块如何使用 Expressive Code 展示代码块。提供的示例基于官方文档,您可以参考以获取更多详细信息。
语法高亮#
常规语法高亮#
1console.log('此代码有语法高亮!')渲染 ANSI 转义序列#
1Standard ANSI colors:2- Dimmed: Black Red Green Yellow Blue Magenta Cyan White 3- Foreground: Black Red Green Yellow Blue Magenta Cyan White 4- Background: Black Red Green Yellow Blue Magenta Cyan White 5- Reversed: Black Red Green Yellow Blue Magenta Cyan White 6
78-bit colors (showing colors 160-171 as an example):8- Dimmed: 160 161 162 163 164 165 166 167 168 169 170 171 9- Foreground: 160 161 162 163 164 165 166 167 168 169 170 171 10- Background: 160 161 162 163 164 165 166 167 168 169 170 171 11- Reversed: 160 161 162 163 164 165 166 167 168 169 170 171 12
1324-bit colors (full RGB):14- Dimmed: ForestGreen - RGB(34,139,34) RebeccaPurple - RGB(102,51,153) 15- Foreground: ForestGreen - RGB(34,139,34) RebeccaPurple - RGB(102,51,153) 16- Background: ForestGreen - RGB(34,139,34) RebeccaPurple - RGB(102,51,153) 17- Reversed: ForestGreen - RGB(34,139,34) RebeccaPurple - RGB(102,51,153) 18
19Font styles:20- Default21- Bold22- Dimmed23- Italic24- Underline25- Reversed26- Strikethrough编辑器和终端框架#
代码编辑器框架#
1console.log('标题属性示例')1<div>文件名注释示例</div>终端框架#
1echo "此终端框架没有标题"1Write-Output "这个有标题!"覆盖框架类型#
1echo "看,没有框架!"1# 如果不覆盖,这将是一个终端框架2function Watch-Tail { Get-Content -Tail 20 -Wait $args }3New-Alias tail Watch-Tail文本和行标记#
标记整行和行范围#
1// 第1行 - 通过行号定位2// 第2行3// 第3行4// 第4行 - 通过行号定位5// 第5行6// 第6行7// 第7行 - 通过范围 "7-8" 定位8// 第8行 - 通过范围 "7-8" 定位选择行标记类型 (mark, ins, del)#
1function demo() {2 console.log('此行标记为已删除')3 // 此行和下一行标记为已插入4 console.log('这是第二个插入行')5
6 return '此行使用中性默认标记类型'7}为行标记添加标签#
1<button2 role="button"3 {...props}4 value={value}5 className={buttonClassName}6 disabled={disabled}7 active={active}8>9 {children &&10 !active &&11 (typeof children === 'string' ? <span>{children}</span> : children)}12</button>在单独行上添加长标签#
1<button2 role="button"3 {...props}4
5 value={value}6 className={buttonClassName}7
8 disabled={disabled}9 active={active}10>11
12 {children &&13 !active &&14 (typeof children === 'string' ? <span>{children}</span> : children)}15</button>使用类似 diff 的语法#
1此行将标记为已插入2此行将标记为已删除3这是常规行1--- a/README.md2+++ b/README.md3@@ -1,3 +1,4 @@4+this is an actual diff file5-all contents will remain unmodified6 no whitespace will be removed either结合语法高亮和类似 diff 的语法#
1function thisIsJavaScript() {2 // 整个块都会以 JavaScript 高亮显示,3 // 并且我们仍然可以为其添加 diff 标记!4 console.log('要删除的旧代码')5 console.log('新的闪亮代码!')6}标记行内的单独文本#
1function demo() {2 // 标记行内的任何给定文本3 return '支持给定文本的多个匹配项';4}正则表达式#
1console.log('单词 yes 和 yep 将被标记。')转义正斜杠#
1echo "Test" > /home/test.txt选择内联标记类型 (mark, ins, del)#
1function demo() {2 console.log('这些是插入和删除的标记类型');3 // return 语句使用默认标记类型4 return true;5}自动换行#
为每个块配置自动换行#
1// 启用换行的示例2function getLongString() {3 return '这是一个非常长的字符串,除非容器极宽,否则很可能无法适应可用空间'4}1// wrap=false 的示例2function getLongString() {3 return '这是一个非常长的字符串,除非容器极宽,否则很可能无法适应可用空间'4}配置换行的缩进#
1// preserveIndent 示例(默认启用)2function getLongString() {3 return '这是一个非常长的字符串,除非容器极宽,否则很可能无法适应可用空间'4}1// preserveIndent=false 的示例2function getLongString() {3 return '这是一个非常长的字符串,除非容器极宽,否则很可能无法适应可用空间'4}可折叠部分#
5 collapsed lines
1// 所有这些样板设置代码将被折叠2import { someBoilerplateEngine } from '@example/some-boilerplate'3import { evenMoreBoilerplate } from '@example/even-more-boilerplate'4
5const engine = someBoilerplateEngine(evenMoreBoilerplate())6
7// 这部分代码默认可见8engine.doSomething(1, 2, 3, calcFn)9
10function calcFn() {11 // 您可以有多个折叠部分3 collapsed lines
12 const a = 113 const b = 214 const c = a + b15
16 // 这将保持可见17 console.log(`计算结果: ${a} + ${b} = ${c}`)18 return c19}20
4 collapsed lines
21// 直到块末尾的所有代码将再次被折叠22engine.closeConnection()23engine.freeMemory()24engine.shutdown({ reason: '示例样板代码结束' })行号#
为每个块显示行号#
1// 此代码块将显示行号2console.log('来自第2行的问候!')3console.log('我在第3行')// 此块禁用行号console.log('你好?')console.log('抱歉,你知道我在第几行吗?')更改起始行号#
5console.log('来自第5行的问候!')6console.log('我在第6行')后续补充#
这篇文章后面会继续追加新的 Markdown 扩展示例。
如果哪次改动把现有渲染效果改坏了,这篇文章也可以顺手拿来当回归检查页用。
如果这篇文章对你有帮助,欢迎分享!
部分信息可能已经过时
















































