扩展 Markdown 语法速查
md-publish 在标准 Markdown(GFM:表格 / 任务列表 / 删除线 / 自动链接)之上,加了少量
结构化组件,让纯文本也能渲染出卡片、徽章、流程、提示框等富版式。所有扩展都是
可选的——不写就是普通 Markdown。代码高亮、mermaid 图、本地图片自动上传照常可用。
调色板(6 色,徽章/卡片/主题色通用):green amber coral blue gray purple。
1. Frontmatter(文档级选项)
写在文件最顶部,两条 --- 之间,key: value 每行一个:
---
title: 我的文档标题 # 覆盖正文首个 # 标题作为页面标题
accent: blue # 主题强调色(上面 6 色之一),影响导航悬停等
nav: auto # auto = 由二级标题(##)自动生成顶部锚点导航;off = 不生成
toc: true # 侧栏目录开关,默认 true
---
全部可省略;省略即用默认值(无强调色、无顶部导航、有侧栏目录、标题取首个 #)。
2. 提示框 callout
:::note
普通说明。框内可以写**任意 markdown**:列表、`代码`、表格都行。
:::
:::tip
小技巧(绿色)。
:::
:::warn
警告(琥珀色)。
:::
:::danger
危险/红线(珊瑚色)。
:::
类型:note(蓝) tip(绿) warn(琥珀) danger(珊瑚) info(灰)。
也可写完整形式 :::callout {type=warn}(warning 等价于 warn)。
3. 网格 + 卡片 grid / card
:::grid {cols=2}
:::card {accent=green title="左卡片标题"}
卡片正文,markdown 自由发挥。
:::
:::card {accent=gray title="右卡片标题"}
另一张卡片。
:::
:::
grid的cols取2或3(默认 2);窄屏自动堆成一列。card的accent(6 色之一)和title都可省略;省略 accent 即中性边框。
4. 流程 steps / step
:::steps
:::step {title="① 前置校验"}
命中即拦截,不下发。
:::
:::step {title="② 路由"}
选供应商。
:::
:::step {title="③ 响应"}
返回结果。
:::
:::
横向排列、自动加 → 箭头;窄屏竖排、箭头变 ↓。title 可省略。
5. 行内徽章 badge
:badge[2 核验不一致]{color=amber}
渲染成彩色小药丸。color 取 6 色之一,非法值回退 gray。
可放在任意行内位置——正文、列表项、甚至表格单元格里:
| 码 | 含义 |
|----|------|
| :badge[1]{color=green} | 一致 |
| :badge[2]{color=amber} | 不一致 |
6. 嵌套规则
容器用相同的 ::: 嵌套,各自用自己的 ::: 收尾(卡片在网格里、提示框里放表格等
都可以)。卡片/提示框/步骤内部可以放普通 markdown、代码块、徽章、甚至再嵌一层容器。
:::grid {cols=2}
:::card {accent=green title="示例"}
:badge[1]{color=green} 正常
```json
{ "result": 1 }
::: :::
---
## 7. 完整小例子
```markdown
---
title: 接口设计
accent: blue
nav: auto
---
# 接口设计
:::tip
本页用扩展 Markdown 写成。
:::
## 一、状态码
:::grid {cols=2}
:::card {accent=green title="大类码(必返)"}
:badge[1 一致]{color=green} :badge[2 不一致]{color=amber}
:::
:::card {accent=gray title="细分码(选返)"}
缺失不影响主流程。
:::
:::
## 二、处理链路
:::steps
:::step {title="① 校验"}
前置拦截
:::
:::step {title="② 核验"}
调用供应商
:::
:::
发布
写好后任选一种方式发布(都读同一份 markdown):
mdpub publish 文件.md # CLI
- VSCode:
MD Publish: 发布当前文件 - Skill:对 Claude 说"把这篇 md 发布到我的服务器"
slug 默认取文件名(中文也可),同名重发覆盖、URL 稳定。安全上默认不开启原始 HTML/JS,组件是受控结构,发布页可放心公开。