Import syntax design for external demo

[PeachScript]

背景

如果仅提供在 .md 中写代码块来生成 demo 的方式，会有以下两个问题：

1. 复杂组件的 demo 也会比较多，.md 会混乱难以管理
2. 在 .md 中写 tsx/jsx 无法得到编辑器的各种辅助（lint、snippets、autocomplete & etc.），在编写复杂 demo 的时候效率会非常低

所以计划在 father-doc 中新增一种 markdown 扩展语法，使得编写者可以主动从外部导入 .tsx/jsx 文件生成 demo。

要求

语法的设计非常重要，因为关乎后续编写者的内容创作，一旦方案确定，后续再难修改。设想之下，大致有如下几点要求：

1. 维持 markdown style，不能有违和感
2. 支持传递文件路径
3. (欢迎补充)

提案

加上 issue 中大家提出的方案，目前共有 5 种备选方案：

1. 去骨去尾代码块方案： ```./demo/Hello.jsx
2. 超链接/图片师出同门方案： $[](./demo/Hello.jsx)
3. UBB 借鉴一刀流方案：[demo=./demo/Hello.jsx]
4. HTML 注释方案：<!-- [demo=./demo/Hello.jsx] -->
5. code 标签降级兼容方案：<code src="./demo/Hello.jsx">fallback 文本</code>

需要特殊说明的是第 3 种方案，此方案可以用类似的语法扩展出更多的自定义语法，一脉相承，比如：

1. 自定义标签语法，渲染类似 antd 的标签组件： [badge=1.0.0-Beta.1 danger]
2. 自定义警告块语法，渲染类似 antd 的 Alert 组件： [alert=天干物燥 title=小心火烛 warn]

讨论

目前前 3 种方案看起来都有一些小问题：

1. 如果次行正好为另一个代码块，无论是 transformer 的 token 识别还是编写者肉眼识别，都会造成干扰
2. 中间的方括号没有没有实际作用
3. 历史感很浓重，毕竟是论坛时代的标签语法

如果大家对这 5 种方案有独特看法，或者有更好的方案，欢迎进行讨论。

[sorrycc]

[$demo](./demo/Hello.jsx)

[sorrycc]

`$demo: ./demo/Hello.jsx`

[PeachScript]

[$demo](./demo/Hello.jsx)

@sorrycc 这个方案是否容易与用户的内容冲突，假设用户需要描述自己的一个内置变量，正好叫 $demo，然后锚点链接过去的话

[vthinkxie]

<!-- [demo=./demo/Hello.jsx]-->

[hstarorg]

$[demo标题](./demo/Hello.jsx) ，参考图片标签 ![图片alt](图片地址), 也就是方案2。中括号可以当成 demo 标题

[rdmclin2]

原来的 mdx 语法是支持复杂demo嵌入的，如

import demo1 from './demo1';

<Playground>
   <demo1 />
</Playground>

但是这种方式有个问题是实际用户看不到demo里面的代码，也无法修改，如果能够修正这个问题，我想用目前的方式也是ok的

[PeachScript]

@rdmclin2 是的，这也是一个方向，只是目前 father-doc 是基于 md 不是 mdx 的，主要考虑到 mdx 提供的便利性其实不比 md + 代码块 + 外部 demo 来得高

[PeachScript]

非常感谢各位提出的宝贵方案，在衡量当下和未来可能出现的需求后，决定采用 code 标签的方案，理由大概如下：

1. code 标签本身是常规语法，即便在普通的 markdown 阅读器或者 GitHub 的 preview 时，也能够做到『降级显示』，比如 <code src="./Normal.jsx">标准模式使用示例</code> 在降级显示时会变成『标准模式使用示例』；
2. code 作为 HTML 标签比较符合工程师的直觉；
3. HTML 标签可以承载更多属性的配置，比如后续覆盖类似 ant.design 的文档场景时，可以启用 glob 和分栏属性以支持批量导入 demo 并分栏显示：<code src="./demo/*.jsx" cols="2">Button 组件的在线 demo</code>。