MDC 语法与组件注册
MDC 让文章作者在 Markdown 中使用 Vue 组件。本文中的示例都可用于 content/docs/ 和 content/blog/；渲染仍由页面里的 ContentRenderer 完成。完整组件索引见 常用组件。
块组件与 Markdown 正文
::组件名 到配对的 :: 是一个组件块。默认插槽里的段落、列表、链接和代码块继续按 Markdown 渲染。
::article-summary{title="本页要点"}
- 普通文本、Markdown 和 Vue 组件可以组合。
- 属性负责数据，插槽负责富文本。
::
行内组件
单个冒号用于行内组件，例如版本 Nuxt 4 和图标 。
版本 :badge[Nuxt 4]{color="info"}
图标 :smart-icon{name="lucide-sparkles" size=18}
简单属性与结构化属性
字符串写在 {} 中。数字、布尔值、数组与对象使用 : 绑定：
::expand-box{title="默认展开" :open="true"}
正文内容。
::
::stat-grid{:items='[{"label":"组件","value":20},{"label":"集合","value":2}]' :columns="2"}
::
复杂数据用组件内的 --- YAML 区域，避免长 JSON 和引号转义。这个区域设置该组件的 props，与文件顶部设置文章元信息的 frontmatter 不同。
- 内容集合
- 2
- 文档与博客
- 公共自定义组件
- 27
- 包含时间线条目与兼容入口
::stat-grid
---
columns: 2
items:
- label: 内容集合
value: 2
description: 文档与博客
- label: 公共自定义组件
value: 27
---
::
命名插槽
组件内部的 #takeaway 把后面的 Markdown 交给同名插槽。这里的 # 是插槽标记，不是文章标题。
::article-summary{title="排版建议"}
默认插槽适合写**背景与重点**。
#takeaway
结论：把一句行动建议放进 takeaway 插槽。
::
嵌套组件
外层使用更多冒号，可清楚区分结束位置。每个组件的开始和结束冒号数保持一致。
准备内容
确定文章读者与结论。
补充示例
加入代码、图表和可操作的清单。
:::doc-timeline{label="写作流程"}
::timeline-item{title="准备内容" date="第一步"}
确定文章读者与结论。
::
::timeline-item{title="补充示例" date="第二步"}
加入代码、图表和可操作的清单。
::
:::
Vue 实现与注册
本站组件位于 app/components/content/。例子：
<template>
<aside>
<p>{{ title }}</p>
<slot />
<slot name="takeaway" />
</aside>
</template>
<script setup lang="ts">
defineProps<{ title?: string }>()
</script>
Nuxt Content 会扫描内容组件目录。本站还通过 app/plugins/content-components.ts 显式注册公共名称，shared/mdc-components.ts 保持 Studio 组件选择器一致；教学示例目录使用按需异步注册。Nuxt UI 的 ::tabs、::callout 等由模块配置映射到 Prose*。
新增公共组件时同步三个位置：Vue 文件、注册插件、Studio 名称清单，然后补充实例文档。组件放到其他目录时，需要全局注册或通过 ContentRenderer 的 components 映射提供，不能仅依赖普通模板的自动导入。
在 <span> 或标题里放插槽，可用 <slot mdc-unwrap="p" /> 去掉默认段落包装。需要段落、列表和代码的正文容器应保留完整 <slot />。
编写约定
- 组件属性使用明确类型；组件中不访问服务端不存在的
window、document。 - 路由链接使用安全 URL 校验；新窗口链接保留
noopener noreferrer。 - 表单控件要有可见标签，折叠和图片预览必须能用键盘操作。
- 检查清单仅在当前页面保存状态；刷新后恢复 Markdown 的初始数据。
- Markdown/MDC 作者属于受信任的内容贡献者，组件功能不能代替内容访问控制。
相关语法以 Nuxt Content Markdown 文档 与 ContentRenderer API 为准。