RhoMD Docs Download

Layout grid + cards

把内容分列排成卡片——用空间结构表达"这几块是平级的、可以横向比较"。 适用于功能对比、选项陈列、产品三选一、团队展示等场景。

When to use

  • ✅ N 个平级选项 让读者横向比较（产品方案 / 套餐 / 工具对比）
  • ✅ 多个并列功能 用卡片陈列（首页 features 区）
  • ✅ 三角形论述（A 方案 / B 方案 / C 方案的客观对比）
  • ✅ 团队 / 案例展示（每张卡片一个人或一个 case）
  • ❌ 单一信息块——用 Callout
  • ❌ 内容差异极大、字数不平衡——卡片高度参差，视觉破碎
  • ❌ 严格序列（step 1 → 2 → 3）——用 Stepper

Basic syntax

\```layout grid cols=3
:::card accent=blue
**方案 A**

短描述 + 一两个要点。
:::

:::card accent=red
**方案 B**

短描述 + 一两个要点。
:::

:::card accent=green
**方案 C**

短描述 + 一两个要点。
:::
\```

渲染：3 列等宽卡片并列；每张顶部有彩色 accent bar；窄屏自动堆叠成单列。

All options

Block-level: ```layout grid

Option Type Default Purpose
cols int (1-6) 2 列数。窄屏 < 720px 自动单列

Card-level: :::card

Option Type Default Purpose
accent enum gray 顶部 accent bar 颜色（6 选 1）

Accent 6 色：

值 视觉 推荐用法
blue 蓝 中性 / 信息 / 主推方案
red 红 警告 / 高风险 / 不推荐
green 绿 推荐 / 通过 / 成功
yellow 黄 提醒 / 需注意
purple 紫 高级 / Pro / 特殊
gray 灰 中性 / 默认（省略 accent 即此）

Examples

Example 1：3 列产品方案

\```layout grid cols=3
:::card accent=gray
**Free**

- 个人使用
- 5 个文档
- 社区支持

$0/月
:::

:::card accent=blue
**Pro**

- 个人专业
- 无限文档
- 邮件支持
- 私有分享

$10/月
:::

:::card accent=purple
**Team**

- 团队协作
- SSO + 审计
- 优先支持
- SLA 99.9%

$50/月
:::
\```

渲染：三张等宽卡片，accent bar 分别是灰/蓝/紫。Pro 方案视觉权重最强（蓝），Team 标记"高级"（紫）。读者扫一眼能感知层级。

Example 2：嵌套 callout

\```layout grid cols=2
:::card accent=green
**推荐方案：A**

> [!INFO]
> A 方案适合 90% 的用户，零配置开箱即用。

详细说明……
:::

:::card accent=red
**不推荐：B**

> [!WARN]
> B 方案需要自己维护服务器，仅高级用户。

详细说明……
:::
\```

渲染：两张卡片，每张内嵌一个 callout（INFO / WARN）。卡片提供布局，callout 提供语义高亮——职责分明。

Example 3：单列（cols=1）

\```layout grid cols=1
:::card accent=blue
完整宽度的卡片，相当于"加了 accent bar 的段落"。
:::
\```

渲染：全宽单卡片。看起来像 callout，但语义不同——这是"被分组的内容块"，不是"高亮提示"。

Example 4：4 列以上 / 6 列

\```layout grid cols=4
:::card accent=blue
功能 1
:::
:::card accent=blue
功能 2
:::
:::card accent=blue
功能 3
:::
:::card accent=blue
功能 4
:::
\```

渲染：4 列等宽。在桌面分辨率下每张卡片 ~250px 宽。超过 4 列内容会很挤——5/6 列只适合极简的图标+一行字。

Plain-text fallback behavior

:::card 是 markdown directive 容器语法（CommonMark Container Blocks 提案）。在不支持 directive 的 reader 里：

:::card accent=blue
**方案 A**
描述
:::

→ :::card accent=blue / ::: 显示为 plain text；卡片内的 markdown 内容正常渲染（粗体、列表、链接等都识别）。

具体各 reader：

Reader 渲染效果
Rho 完整 grid + cards + accent
GitHub web :::card accent=blue 字面量 + 卡片内 markdown 正常
Obsidian 部分插件支持（如 obsidian-callout / containers）；默认显示字面量
VS Code 默认预览 ::: 字面量 + 内容正常
cat / less 源文件 plain text

所有情况内容可读，只是 layout 视觉信息丢失。

Common pitfalls

1. accent 值打错

:::card accent=skyblue   ← ❌ 不识别，回落 gray
:::card accent=BLUE      ← ⚠️ 大小写敏感，建议小写
:::card accent=blue      ← ✅

只有 6 个合法值：blue / red / green / yellow / purple / gray。

2. 忘记关 :::

\```layout grid cols=2
:::card accent=blue
内容 A
                ← ❌ 缺少 :::
:::card accent=red
内容 B
:::
\```

→ 整个 layout 块解析失败。每个 :::card 必须配对应的 ::: 关闭。

3. cols 数和 card 数不匹配

\```layout grid cols=3
:::card accent=blue
A
:::
:::card accent=red
B
:::
\```

→ 2 张 card 在 3 列布局里，第 3 列空着。不会报错，但视觉不对称。要么改 cols=2，要么补一张卡。

4. 卡片内容字数严重不平衡

\```layout grid cols=2
:::card accent=blue
A 方案：超长描述、5 段、3 个列表、嵌套 callout、代码块……
:::
:::card accent=red
B 方案：一句话。
:::
\```

→ 左卡片很高，右卡片像被截断。视觉破碎。 解决：补充右卡内容到对等长度，或改用 Stepper（一次显示一个），或改用 Tabs。

5. 把 layout 嵌套到 layout

\```layout grid cols=2
:::card
\```layout grid cols=2     ← ❌ 不要嵌套
:::card
:::
:::card
:::
\```
:::
\```

→ 内层 grid 解析行为未定义。Layout 不应嵌套。如果要复杂结构，改用 Stepper 或重新设计页面。

6. 卡片里塞 interact 块——可以，但注意 hydration

:::card accent=blue
\```interact
slider x 0 10 5 1
template stl:
[选中] -> [{x}]
\```
:::

✅ 完全合法（Nested DSL 支持）。但卡片高度会随 interact 渲染产物变化——拖滑块时如果输出高度变，相邻卡片会跟着重排。建议给 interact 块固定 min-height，或把它放到独立行不嵌套。

See also