企业官网建设流程全解析

Comark是一个开源的 Markdown 解析与渲染库，它的组件语法让你可以在 Markdown 中直接书写UI 组件——无需切换框架模板，块级组件、行内组件、属性(props)、插槽(slots)和嵌套组件都能"原生"地写在文档里，并可渲染到 Vue、React、Svelte、Angular、HTML 和终端。

1. 为什么要在 Markdown 里写组件？

传统方案里，想让 Markdown 承载交互式 UI，往往要引入 MDX 这类"编译期"方案，或者在渲染层做大量 hack。Comark 的思路更轻：

• 组件是可选语法：组件由内置的components插件 解析，默认启用，不需要额外安装或注册；
• 还是标准 Markdown：CommonMark + GFM 语法不变，组件语法是"叠加"而非"替换"；
• 一份内容，处处渲染：同一段带组件的 Markdown，可渲染到 Vue / React / Svelte / Angular / HTML / 终端。

2. 快速上手：块级组件语法（Block）

块级组件使用::组件名开头、独占整行，语法一目了然：

::alert{type="info"} 这是一条**重要提示**，内容支持完整的 Markdown 语法！ ::

解析后它就是一个普通的组件 AST 节点（如['alert', { type: 'info' }, '…']），再由你选定的渲染器映射到真实的 UI 组件上。更多块级组件写法（卡片、空组件等）见 docs/content/2.syntax/2.components.md。

3. 行内组件：把 UI 嵌进句子中间

行内组件以单冒号:组件名书写，可以出现在任意文字中间：

示例：

当前状态是 :badge[Active]{color="green"}，点击 :button[提交]{type="primary"} 继续。

对新手来说，这是最"无感"的用法——写文档的人甚至意识不到自己在写 UI。

4. 传参（Props）的三种姿势

4.1 内联属性{...}

适合标量型属性，支持键值对、布尔、ID、class 等多种写法：

::component{prop="value" bool #custom-id .class-name} ::

4.2 YAML 块属性

属性多、结构复杂（数组、对象、嵌套）时，直接在组件体内写 YAML，官方提供两种等价风格：

::data-table ```yaml [props] columns: - name: 姓名 field: name sortable: true options: striped: true pageSize: 10

::

💡 关键优势：对象仍是对象、数组仍是数组、数字/布尔按原类型解析——**组件收到的是完整类型化的 props**，而不是字符串。 ### 4.3 两种写法可以混用 内联属性和 YAML 属性可组合使用：**YAML 属性优先级更高，`class` 值会自动合并**。 ## 5. 插槽（Slots）：给组件传结构化内容 块级组件直接包裹的内容进入**默认插槽**；也可以用 `#插槽名` 声明**命名插槽**： ```mdc ::card #header ## 文章标题 #content 这是正文，支持 **Markdown** 排版。 #footer 发布于 2024-01-15 ::

⚠️ 一个小坑：如果同时使用 YAML 块属性，它必须紧跟在::组件名行之后、写在所有#插槽之前，否则不会生效。

6. 嵌套组件：多写几个冒号就行

组件里再放组件，只需在嵌套层多加冒号（不强制，但保持视觉对齐是好习惯）：

::level-1 :::level-2 ::::level-3 三层嵌套的内容 :::: ::: ::

解析器通过匹配开闭标签来识别层级，深层嵌套、混合段落都能正确处理。

7. 进阶：数据绑定，让组件"读"运行时数据

属性值加:前缀（如:label="data.user.name"）后，Comark 会在渲染时解析它：

1. 是合法 JSON（如5、"foo"、{"a":1}）→ 原样使用；
2. 否则按点路径在渲染上下文中查找，共 4 个命名空间：

这样，文档作者不必硬编码值，同一篇 Markdown 在不同运行时环境下能呈现不同内容——这也是 AI 流式输出场景下组件能"活"起来的关键。

8. 在框架里落地：只需一步映射

组件语法解析出的只是 AST，最后一步是把你框架里的真实组件"接"上去。以 Vue 为例，把组件名映射到Markdown的componentsprop 即可（React / Svelte / Angular 同理）：

<script setup> import Alert from './components/Alert.vue' const components = { alert: Alert } </script> <template> <Markdown :components="components">{{ content }}</Markdown> </template>

各框架的完整用法分别见 docs/content/3.rendering/3.vue.md、docs/content/3.rendering/5.react.md、docs/content/3.rendering/6.svelte.md、docs/content/3.rendering/7.angular.md。

9. 学习路线小结

掌握::组件名{props}、:组件名[内容]、YAML 块属性、命名插槽这四件套，你就已经能在 Markdown 里自由搭建 UI 了。想动手实验，仓库也提供了现成示例：examples/3.plugins/vue-vite-binding/ 和 examples/2.vite/vue-streaming/，克隆仓库后即可运行：

git clone https://gitcode.com/gh_mirrors/com/comark