[RFC] dumi 2.0 demo grid

[PeachScript]

为了实现 antd v4 文档中的 demo 分栏效果，暂时想到的几种产品方案，欢迎给出建议或新的 idea。

以下每种方案会分为 3 个部分介绍，分别是：

1. Markdown：展示在 Markdown 文件中的语法
2. GitHub 预览：展示在脱离 dumi 编译、直接展示在 GitHub 预览页的效果
3. 思路及逻辑：介绍实现该方案的思路及逻辑

换行/段落区分版

Markdown:

---
demo:
  # 同 antd 栅格规则，可以做成默认值直接配 cols: true
  cols:
    xs: 1
    sm: 1
    md: 2
    lg: 2
    xl: 2
    xxl: 3
---

<code src="./1.tsx">我在左边</code>
<code src="./2.tsx">我在右边</code>
<code src="./3.tsx">我还在左边</code>
<code src="./4.tsx">我还在右边</code>

<code src="./full-row.tsx">我占一整行</code>

GitHub 预览：

我在左边
我在右边
我还在左边
我还在右边

我占一整行

思路及逻辑：

用法上，用换行分割的 code 代表启用分栏，用段落分割的 code 代表独占一行；
实现上，通过遍历 mdast 拿到 p 节点，通过判断内部 code 的数量来决定是否包裹栅格容器，再由 frontmatter 配置栅格规则、在运行时做分栏；
优势是使用简单、排版灵活、可针对不同页面做定制，默认 cols 不开启也不存在 Breaking Change。

模仿表格版（不支持运行时栅格，已排除）

Markdown:

<code src="./left.tsx">我在左边</code> | <code src="./right.tsx">我在右边</code>
<code src="./left-again.tsx">我还在左边</code> | <code src="./right-again.tsx">我还在右边</code>
<code src="./full-row.tsx">我占一整行</code>

GitHub 预览：

我在左边 | 我在右边
我还在左边 | 我还在右边

我占一整行

思路及逻辑：

用法上，使用管道符 | 作为分栏的标识符，用户可根据实际情况决定分割次数；
实现上，通过遍历 mdast 拿到 code 和 | 节点，去除 | 并套一层 DemoGrid 容器 + flex 布局实现分栏，或者直接加个 token parser 处理 |；
优势是简单、灵活、预览友好（为了更像表格也可以把左右两边的 | 补齐，没有 --- 不会触发表格语法）。

声明式（不支持运行时栅格，已排除）

Markdown:

<code src="./left.tsx" align="left">我在左边</code>
<code src="./right.tsx" align="right">我在右边</code>
<code src="./left-again.tsx" align="left">我还在左边</code>
<code src="./right-again.tsx" align="right">我还在右边</code>
<code src="./full-row.tsx">我占一整行</code>

GitHub 预览：

我在左边
我在右边
我还在左边
我还在右边
我占一整行

思路及逻辑：

用法上，不拓展新语法，而是基于 dumi 1.0 的 code 标签拓展 align 属性，但只能支持双栏；
实现上，通过遍历 mdast 拿到带 align 的 code 节点，并套一层 DemoGrid 容器 + flex 布局实现分栏；
优势是一目了然，缺点是只能双栏。

容器版

Markdown:

<DemoGrid cols="2">
  <code src="./left.tsx">我在左边</code>
  <code src="./right.tsx">我在右边</code>
  <code src="./left-again.tsx">我还在左边</code>
  <code src="./right-again.tsx">我还在右边</code>
</DemoGrid>
<code src="./full-row.tsx">我占一整行</code>

GitHub 预览：

我在左边 我在右边 我还在左边 我还在右边 我占一整行

思路及逻辑：

用法上，使用 DemoGrid 容器显式做分栏，用户可根据实际情况设置 cols 决定分割次数；
实现上，通过遍历 mdast 拿到 DemoGrid 节点，对内部节点做追加编译（remark 默认不编译标签内部的内容）；
优势是 demo 数量多的时候比较容易整体控制，缺点是 CSS Grid 兼容性差一些，还是可以重排节点用 flex 布局。

通配版（已排除）

Markdown:

<code src="./demos/*.tsx" cols="2">一组 demo</code>

GitHub 预览：

一组 demo

思路及逻辑：

用法上，不拓展新语法，而是基于 dumi 1.0 的 code 标签拓展通配符批量引入 demo，用户可根据实际情况设置 cols 决定分割次数；
实现上，通过遍历 mdast 拿到 code 节点，对通配符的 demo 做具体展开，再套一层 DemoGrid 容器 + flex 布局实现分栏；
优势是 demo 增加的时候维护成本比较低，缺点是有点黑、预览不友好、且排序较麻烦。

[xierenyuan]

感觉声明式 有阅读优势, 模仿表格的对于上手或者新同学 有理解成本

[migodev42]

凭感觉投容器版一票

[cnyballk]

比较倾向容器版，感觉比模仿表格版更好阅读，兼容性应该不是什么大问题，用其他css属性模拟下 Grid 也可以？模仿表格版的 | 的格式化会不会容易错乱？之前写表格的时候，markdown 有时候格式化会乱一下（可能是我自己的问题）

[mortalYoung]

我也投容器版一票，表格版的 markdown 代码读起来太费劲了 声明式只能支持双栏感觉日后会成为一个大的问题

[afc163]

能搞个 dumi-plugin-antd 兼容一下 antd 目前的写法么？

[PeachScript]

原计划是写个脚本把 antd 的 demo 都迁移成新的写法，demo 写在 tsx 里可以天然带类型检查和其他编码辅助

[afc163]

我更倾向做编译时和运行时兼容，写法允许保持不变，也允许用新的 code 引入方式。

[arvinxx]

能不能让 md 维持现状，然后在渲染上做控制呢？我感觉md这个是不是应该具有多主题下的复用性？
假设要让官网在超宽屏下变成三栏模式呢？这个md还能复用吗？

[PeachScript]

能不能让 md 维持现状，然后在渲染上做控制呢？

md 的现状是 demo 和文本混排的，如果用法不做区分、就没法区分出哪些 demo 要参与分栏哪些不参与

假设要让官网在超宽屏下变成三栏模式呢

这个的确是个场景，分栏要支持响应式断点才行

[MadCcc]

现在 antd 的分栏是支持断点的，宽度不够就只会显示一栏。感觉上应该是渲染时自动排版更好一些，用样式或者直接用 antd 的 grid 控制。是否分栏显示感觉可以做成配置？

[PeachScript]

是的，断点之前考虑漏了，部分方案应该要 pass 掉

是否分栏显示感觉可以做成配置？

做成页面配置就意味着整页生效，但可能有些 demo 会希望整行展示？

[xrkffgg]

声明式 ~

[PeachScript]

由于要考虑运行时动态栅格（比如手机是一栏、电脑是两栏、大屏显示器是三栏），原有的『模仿表格版』及『声明式』都惨遭淘汰，现新增一类『换行/段落区分版』，个人觉得体验更好而且可以实现运行时动态栅格，大家再看看