组件特性

常用组件

MDC 写法、28 个自定义组件、Nuxt UI 内容组件及 Markdown 渲染覆盖的完整索引。

组件使用方式

Estel Docs 基于 Nuxt Content MDC 语法，把 Vue 组件放进 Markdown。组件名使用 kebab-case，例如：

ECard.vue → ::e-card
ETabs.vue → ::e-tabs
FileTree.vue → ::file-tree
ButtonLink.vue → ::button-link

从 MDC 语法与注册开始学习。新增组件的说明与可复制代码和交互演示都是实际 Markdown 页面，博客示例见用 MDC 组织技术文章。

进阶组件的 API 与示例和交互演示已补充数据、接口和阅读互动能力。

组件清单

组件	用途	关键参数
`ECard`	卡片容器，基于 `UPageCard`。	`title`、`description`、`icon`、`img`、`spotlight`、`content`
`ETabs`	标签页容器，从默认插槽读取 tab。	子项 `label`、`icon`
`Stack`	将多个内容块放入分割卡片中。	默认插槽
`FileTree`	展示文件/目录结构。	`tree`、`title`、`icon`、`autoSlash`、`showArrow`、`showIcon`
`CodeTree`	基于 ProseCodeTree 展示代码文件树。	透传属性
`ButtonLink`	按钮式链接。	`to`、`href`、`target`、`blank`、`icon`、`leftIcon`、`rightIcon`、`trailingIcon`、`variant`、`size`、`color`
`Playground`	嵌入 StackBlitz 或 CodeSandbox。	`provider`、`id`、`repo`、`branch`、`dir`、`file`、`title`
`ReadMore`	阅读更多提示卡片。	`to`、`title`、`description`、`icon`、`color`、`variant`
`SmartIcon`	自动识别 Iconify 图标、Emoji 或图片 URL。	`name`、`size`
`ColorModeSwitch`	大尺寸明暗模式切换开关。	无
`Alert`	兼容旧文章中的 `::alert`。	`title`、`icon`、`type`、`color`、`to`、`target`、`external`、`showLinkIcon`
`ArticleSummary`	文章摘要、结论或阅读要点。	`title`、`icon`；默认与 `takeaway` 插槽
`ExpandBox`	折叠补充说明、FAQ、长输出。	`title`、`open`；默认插槽
`LinkCard`	参考文献或文档入口卡片。	`title`、`to`、`description`、`icon`、`target`；默认插槽
`QuoteBlock`	引用正文与来源署名。	`author`、`source`、`to`；默认插槽
`StatGrid`	指标与成果数字展示。	`items`、`columns`
`DocTimeline`	更新日志、事件或调查过程。	`label`；嵌套 `TimelineItem`
`TimelineItem`	时间线条目，正文支持 Markdown。	`title`、`date`、`datetime`；默认插槽
`TaskChecklist`	可勾选的阅读/操作检查清单。	`title`、`items`、`readonly`、`storageKey`
`ImageGallery`	图片网格与键盘可操作的大图预览。	`title`、`images`、`columns`
`ApiEndpoint`	接口方法、路径、认证与请求/响应示例。	`path`、`method`、`title`、`auth`、`status`；request/response 插槽
`ParameterTable`	参数类型、必填、弃用、默认值与枚举。	`title`、`parameters`
`DataTable`	搜索、排序、分页和 CSV 导出的结构化数据表。	`title`、`columns`、`rows`、`searchable`、`pageSize`、`exportable`
`PackageInstall`	切换 pnpm/npm/yarn/bun 并复制安装命令。	`packages`、`dev`、`title`
`ImageCompare`	可拖动与键盘操作的图片前后对比。	`beforeSrc`、`afterSrc`、`beforeAlt`、`afterAlt`、`title`、`initialPosition`
`GlossaryTerm`	行内术语解释，支持原生 popover。	`term`、`definition`
`ContentQuiz`	当前页面的单选阅读自测。	`question`、`choices`、`answer`、`explanation`
`DownloadCard`	站内文件下载或外部下载链接。	`title`、`href`、`filename`、`description`、`version`、`size`

表中共 28 个公共自定义组件。FileTreeItem 是 FileTree 的内部递归节点，使用者应传 tree，不直接写 ::file-tree-item。CodeTree 是代理组件，Markdown 的 ::code-tree 默认由 Nuxt UI 映射至同一底层 ProseCodeTree。

Nuxt UI 提供的 MDC 组件

以下 24 个语法入口由当前安装的 Nuxt UI 4 的 MDC 映射提供，实际实现为 Prose*，并非本站重新实现：

用途	MDC 入口
提醒	`::callout`、`::note`、`::tip`、`::warning`、`::caution`
卡片	`::card`、`::card-group`
代码	`::code-group`、`::code-collapse`、`::code-preview`、`::code-tree`、`:code-icon`
分组交互	`::accordion` + `::accordion-item`、`::collapsible`、`::tabs` + `::tabs-item`
文档说明	`::steps`、`:field`、`::field-group`
行内内容	`:badge`、`:icon`、`:kbd`、`:prompt`

卡片、标签页等旧名称继续可用。::callout 使用 color；本站 ::alert 额外兼容旧 type。新文档优先参考当前 Nuxt UI Typography，不要套用已过时的 shadcn 模板属性。

ProseH1～ProseH6、ProsePre、ProseImg、ProseStrong、ProseStyle 共 10 个文件覆盖标题、代码块、图片图注、粗体样式和公式生成的 CSS。直接写 # 标题、代码围栏、![图片](/logo.png) 或 **重点** 即可，不需要写 ::prose-h1。ProseStyle 是内部渲染适配，保证 MathJax 的样式在 SSR 和客户端一致；其余段落、列表、表格、链接等使用上游 Prose 组件。

教学示例组件

app/components/example/ 下的 9 个组件按需全局注册，供讲解和实验使用：ExampleAlert、ExampleCard、ExampleTitle、ExampleHero、ExampleIconCard、ExampleLandingHero，以及 ExampleFulltextContentSearch、ExampleFulltextFusejs、ExampleFulltextMiniSearch。写法例如 ::example-title。搜索示例会查询本站内容；文章排版优先使用上面的公共内容组件。原有博客中的 ::example-title 也能继续渲染。

ECard

用于创建内容卡片，可展示标题、描述、图标、图片和插槽内容。

::e-card{title="功能卡片" description="用于突出展示一段内容" icon="lucide-sparkles"}
这里是卡片正文，支持 **Markdown**。
::

带图片：

::e-card{title="图片卡片" img="/images/default-blog.jpg"}
图片会展示在卡片内部。
::

ETabs

ETabs 会读取默认插槽中的 div 节点，并从其 props 中获取 label 与 icon。

::e-tabs
  ::div{label="pnpm" icon="simple-icons-pnpm"}
  ```bash
  pnpm install
  ```
  ::

  ::div{label="npm" icon="simple-icons-npm"}
  ```bash
  npm install
  ```
  ::
::

Stack

Stack 适合把多个段落、图片或代码块按分割线堆叠展示。

::stack
  ::div
  第一段内容。
  ::

  ::div
  第二段内容。
  ::
::

FileTree

FileTree 使用 tree 数组描述目录结构。

::file-tree{title="项目结构" :tree='[
  { "app": ["app.vue", { "components": ["ThemeSettings.vue"] }] },
  { "content": ["docs/", "blog/"] },
  "nuxt.config.ts"
]'}
::

约定：

文件名用字符串表示。
目录用对象表示。
^文件名^ 可标记高亮。
+文件名 / -文件名 可表示新增/删除差异。

CodeTree

CodeTree 透传给 Nuxt UI ProseCodeTree，适合展示多个代码文件。

::code-tree{defaultValue="nuxt.config.ts"}
```ts [nuxt.config.ts]
export default defineNuxtConfig({})
```

```vue [app/app.vue]
<template>
  <NuxtPage />
</template>
```
::

ButtonLink

用于在文档中放置按钮链接。

::button-link{to="/docs" icon="lucide-book-open" trailingIcon="lucide-arrow-right" variant="solid" size="md"}
进入文档
::

外链：

::button-link{href="https://nuxt.com" blank=true icon="simple-icons-nuxtdotjs"}
Nuxt 官网
::

Playground

用于嵌入 StackBlitz 或 CodeSandbox。默认点击“加载在线示例”后再连接外部网站，避免读文章时自动启动在线 IDE。确实需要自动加载时设置 :autoload="true"。

::playground{provider="stackblitz" repo="nuxt/nuxt" branch="main" file="package.json" title="Nuxt Playground"}
::

支持：

provider="stackblitz"
provider="codesandbox"
id 模式
GitHub repo + branch + dir + file 模式

用于给出延伸阅读入口。

::read-more{to="/docs/简单文档/deployment" title="继续阅读部署指南" icon="lucide-cloud" color="primary"}
了解静态生成、SSH 发布、微信签名服务和版本回滚。
::

SmartIcon

SmartIcon 会根据 name 自动判断：

Iconify 图标名。
Emoji。
图片 URL。

:smart-icon{name="lucide-star" size=24}
:smart-icon{name="🚀" size=24}
:smart-icon{name="/favicon.ico" size=24}

ColorModeSwitch

用于展示一个较大的明暗模式开关。

::color-mode-switch
::

编写新组件的建议

新增内容组件时建议：

放在 app/components/content/ 下；公共 API 同时加入 app/plugins/content-components.ts 和 shared/mdc-components.ts，让 Markdown 注册与 Studio 选择器保持一致。
使用明确的 props 类型。
保持 SSR 安全，避免在服务端直接访问 window 或 document。
提供 props、插槽、可复制代码及真实渲染示例，并在 docs/blog 两种页面验证。
如果组件依赖外部脚本，应使用 ClientOnly 或在 onMounted 中加载。

可扩展方向

为每个内容组件补充独立 API 页面。
自动生成组件 props 文档。
投票、反馈和需要跨设备同步的进度属于有后端的新功能；现有检查清单可通过 storageKey 保存到当前浏览器。
将组件示例纳入 E2E 截图测试，防止样式退化。

编辑页面或提交问题

部署服务

在 GitHub 生成静态站点，通过 SSH 发布到 Nginx，微信接口由独立 Go 服务提供。

Alert

展示提示、警告和状态信息的提醒组件。