扩展 Markdown 语法速查

更新于 2026-07-02

扩展 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="右卡片标题"}
另一张卡片。
:::
:::

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

slug 默认取文件名(中文也可),同名重发覆盖、URL 稳定。安全上默认不开启原始 HTML/JS,组件是受控结构,发布页可放心公开。