cloudcannon-snippets

CloudCannon 片段

片段允许编辑者在 CloudCannon 富文本内容编辑器中插入和编辑复杂标记（组件、短代码、嵌入内容）。本技能涵盖 SSG 层（如何导入和构建组件）以及 CloudCannon 层（用于向编辑器说明语法的 _snippets 配置）。

适用场景

• 为新的或现有的 CloudCannon 网站添加片段支持
• 为内容编辑器配置 MDX 组件（Astro、Next.js）、Hugo 短代码或 Eleventy 短代码和包含文件
• 将内联 HTML 片段（figure、video、details）添加到 Markdown 内容中
• 调试片段解析、往返转换或工具栏问题

不适用场景

• 组件应当是页面构建器区块，而非内联内容 — 编辑者从结构中选择区块，而不是从富文本工具栏中选择。请参阅 cloudcannon-configuration 和迁移技能中的页面构建指南。
• 让现有的已渲染元素可直接编辑 — 请使用 cloudcannon-visual-editing。片段用于插入新标记；可编辑区域则用于编辑页面上已有的标记。
• 不含组件或内联 HTML 的纯 Markdown 内容 — 无需配置片段

目录

文档	阅读时机
snippets.md	从这里开始。介绍两层的概况、配置层级、方案选择、片段属性、工具栏设置，以及 .md 文件中的原始 HTML 片段
template-based.md	组件语法与内置模板匹配（最常见的方案）
raw.md	组件需要自定义语法（例如 client:load、非标准属性）
built-in-templates.md	了解内置 MDX、Hugo 和 Eleventy 模板、导入包及解析器内部机制
gotchas.md	预防性规则 — 常见陷阱及其解决方法
troubleshooting.md	按症状索引 — 出现问题时从这里开始，它会指引你找到对应规则

特定于 SSG：

SSG	文档
Astro	astro/overview.md — MDX 技术栈、astro-auto-import，何时使用 MDX 与原始语法
Hugo	hugo/overview.md — 短代码、内置短代码导入、选择 Hugo 模板
Eleventy	eleventy/overview.md — 短代码和包含文件、选择 Liquid 或 Nunjucks 模板、{% raw %}
Next.js	nextjs/overview.md — @next/mdx、next-mdx-remote 或内容层、共享组件映射

快速判断

情况	方案
组件语法与内置模板匹配	基于模板 — 参见 template-based.md
额外语法、SSG 指令、自定义解析	原始格式 — 参见 raw.md
.md 中的内联 HTML（<figure>、<video>）	原始片段 — 参见 snippets.md § 内联 HTML 的原始片段
同一组件出现在集合中 3 个或更多文件的开头或结尾	可以考虑使用布局字段 — 按照 snippets.md § 片段还是布局字段？ 中的测试进行判断，并询问用户

大多数配置会对简单组件使用基于模板的方案，对带有 SSG 专用指令的内容使用原始格式。

检查清单

开始前请阅读，并在完成后逐项确认。

• 内容文件中使用的每个组件都有一个 _snippets 条目
• 相关内容块的 _editables 中包含 snippet: true
• 每个片段都能正确往返（通过编辑器插入、保存、重新打开 — 标记保持不变）
• 已为片段字段配置 _inputs（图片字段设置 type: image 等）
• 已配置片段预览（含图片的片段设置 view: gallery）
• picker_preview 使用静态值（而非 key: 查找，因为它们在选择器上下文中无法解析）

常见错误

借口	事实
“内置模板可以处理这个问题”	验证往返过程。内置模板存在已知边缘情况，详见 gotchas.md。
“我稍后再配置片段工具栏”	没有工具栏，编辑者就无法插入片段。现在就将 snippet: true 添加到 _editables。
“这个组件太小众，不适合做成片段”	如果编辑者会在内容中遇到它，就需要能够编辑它。请进行配置。
“在内容中使用导入语句没问题”	从一个共享位置解析组件（Astro：astro-auto-import；Next.js：mdx-components.tsx 或共享组件映射），避免在内容文件中使用导入语句。Hugo 和 Eleventy 的短代码无需导入。
“我可以用 _snippets_imports 来做这件事”	不要这样做。它会加载可能错误匹配的兜底匹配器。请编写明确的 _snippets 条目。只有导入才能提供的预构建片段（Hugo 的内置短代码、Eleventy 的 {% raw %}）是例外，请按名称 include。
“我配置了 _snippets，片段就搞定了”	如果没有在 astro.config.mjs 中接入 astro-auto-import，并且没有从 MDX 文件中移除 import 行，编辑者仍会在 MDX 内容顶部看到原始 import 语句。四个流水线步骤缺一不可，详见 astro/overview.md § MDX setup pipeline。
“在 MDX 中使用原始 HTML 编写内联图片网格没问题”	编辑者无法安全地编辑原始的 <div class="grid"> + <Image> 代码块。请将其提取为自闭合的 <Gallery images={[{src, alt}, ...]} /> 组件（自动导入），并添加匹配的 _snippets 条目，详见 template-based.md § Array-of-objects props。另请参阅 cc-friendly-conventions.md § Image galleries in MDX content。