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