cloudcannon-snippets

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CloudCannon Snippets

Snippets let editors insert and edit complex markup (components, shortcodes, embeds) inside CloudCannon's rich text Content Editor. This skill covers both the SSG layer (how components are imported/built) and the CloudCannon layer (

_snippets

config that teaches the editor the syntax).

Snippets 让编辑者能够在 CloudCannon 的富文本 Content Editor 中插入和编辑复杂标记（组件、shortcode、嵌入内容）。该 skill 涵盖 SSG 层（组件的导入/构建方式）以及 CloudCannon 层（通过

_snippets

配置让编辑器识别语法）。

When to use

何时使用

Adding snippet support to a new or existing CloudCannon site
Configuring MDX components, Hugo shortcodes or Eleventy shortcodes and includes for the Content Editor
Adding inline HTML snippets (figure, video, details) to markdown content
Debugging snippet parsing, round-trip, or toolbar issues

为新的或现有 CloudCannon 站点添加 snippet 支持
配置 MDX 组件、Hugo shortcode 或 Eleventy shortcode 与 include，以供 Content Editor 使用
向 markdown 内容中添加内联 HTML snippet（figure、video、details）
调试 snippet 解析、往返或工具栏问题

When not to use

何时不应使用

The component should be a page-builder block, not inline content — editors pick blocks from a structure, not from the rich text toolbar. See
```
cloudcannon-configuration
```
and the migration skill's page-building guide.
Making an existing rendered element editable in place — that is
```
cloudcannon-visual-editing
```
. Snippets insert new markup; editable regions edit markup already on the page.
Plain markdown content with no components or inline HTML — no snippet configuration is needed

组件应当是 page-builder block，而不是内联内容——编辑器从结构中选择 block，而不是从富文本工具栏中选择。请参阅
```
cloudcannon-configuration
```
和迁移 skill 的页面构建指南。
让现有的已渲染元素支持原地编辑——这属于
```
cloudcannon-visual-editing
```
。Snippet 会插入新标记；可编辑区域用于编辑页面上的现有标记。
不含组件或内联 HTML 的纯 markdown 内容——无需配置 snippet

Doc	When to read
snippets.md	Start here. Overview of both layers, configuration hierarchy, which approach to use, snippet properties, toolbar setup, raw HTML snippets in `.md` files
template-based.md	Component syntax matches a built-in template (most common path)
raw.md	Component needs custom syntax (e.g. `client:load` , non-standard attributes)
built-in-templates.md	Understanding built-in MDX, Hugo and Eleventy templates, the import bundle, parser internals
gotchas.md	Preventative rules — the pitfalls and their workarounds
troubleshooting.md	Symptom index — start here when something is already broken, it routes to the rule

SSG-specific:

SSG	Doc
Astro	astro/overview.md — MDX stack, `astro-auto-import` , when to use MDX vs raw
Hugo	hugo/overview.md — shortcodes, built-in shortcode imports, picking a Hugo template
Eleventy	eleventy/overview.md — shortcodes and includes, picking a Liquid or Nunjucks template, `{% raw %}`

文档	阅读时机
snippets.md	从这里开始。概述两个层、配置层级、应采用哪种方式、snippet 属性、工具栏设置，以及 `.md` 文件中的原始 HTML snippet
template-based.md	组件语法与内置模板匹配（最常用路径）
raw.md	组件需要自定义语法（例如 `client:load` 、非标准属性）
built-in-templates.md	了解内置的 MDX、Hugo 和 Eleventy 模板、导入 bundle 与 parser 内部机制
gotchas.md	预防性规则——常见陷阱及其解决方法
troubleshooting.md	症状索引——当已有功能出现问题时从这里开始，它会将你引导至对应规则

SSG 专用：

SSG	文档
Astro	astro/overview.md——MDX stack、 `astro-auto-import` 、何时使用 MDX 与 raw
Hugo	hugo/overview.md——shortcode、内置 shortcode 导入、选择 Hugo 模板
Eleventy	eleventy/overview.md——shortcode 和 include、选择 Liquid 或 Nunjucks 模板、 `{% raw %}`

Quick decision

快速决策

Case	Approach
Component syntax matches a built-in template	Template-based — see template-based.md
Extra syntax, SSG directives, custom parsing	Raw — see raw.md
Inline HTML in `.md` ( `<figure>` , `<video>` )	Raw snippets — see snippets.md § Raw snippets for inline HTML
Same component at the start or end of 3+ files in a collection	Maybe a layout field — apply the tests in snippets.md § Snippet or layout field? and ask the user

Most setups use template-based for simple components and raw for anything with SSG-specific directives.

场景	方式
组件语法与内置模板匹配	基于模板——请参阅 template-based.md
额外语法、SSG 指令、自定义解析	Raw——请参阅 raw.md
`.md` 中的内联 HTML（ `<figure>` 、 `<video>` ）	Raw snippet——请参阅 snippets.md § .md 文件中的原始 HTML snippet
同一组件出现在某个 collection 的 3 个及以上文件的开头或结尾	可能是 layout 字段——请应用 snippets.md § Snippet 还是 layout 字段？中的测试并询问用户

大多数设置对于简单组件使用基于模板的方式，对于包含 SSG 专用指令的内容使用 raw。

Checklist

检查清单

Read this before starting and verify every item when done.

Every component used in content files has a
```
_snippets
```
entry
```
_editables
```
includes
```
snippet: true
```
on relevant content blocks
Each snippet round-trips correctly (insert via editor, save, reopen — markup unchanged)
```
_inputs
```
are configured for snippet fields (image fields get
```
type: image
```
, etc.)
Snippet previews are configured (
```
view: gallery
```
for image-bearing snippets)
```
picker_preview
```
uses static values (not
```
key:
```
lookups, which don't resolve in picker context)

开始前请阅读本文，并在完成后逐项验证。

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

Common mistakes

常见错误

Excuse	Reality
"The built-in templates handle this"	Verify the round-trip. Built-in templates have known edge cases — see gotchas.md.
"I'll configure the snippet toolbar later"	No toolbar means editors can't insert snippets. Add `snippet: true` to `_editables` now.
"This component is too niche for a snippet"	If editors encounter it in content, they need to be able to edit it. Configure it.
"Import statements in content are fine"	Use auto-import (Astro: `astro-auto-import` ) to keep imports out of content files. Hugo and Eleventy shortcodes need no import.
"I can use `_snippets_imports` for this"	Don't. It loads catchall matchers that can match incorrectly. Write explicit `_snippets` entries. Pre-built snippets only an import provides (Hugo's built-in shortcodes, Eleventy's `{% raw %}` ) are the exception — `include` them by name.
"I configured `_snippets` , snippets are done"	Without `astro-auto-import` wired in `astro.config.mjs` AND the `import` lines removed from MDX files, editors still see raw `import` statements at the top of MDX content. All four pipeline steps are required — see astro/overview.md § MDX setup pipeline.
"Inline image grid in MDX is fine as raw HTML"	Editors can't safely edit raw `<div class="grid">` + `<Image>` blocks. Extract to a self-closing `<Gallery images={[{src, alt}, ...]} />` component (auto-imported) with a matching `_snippets` entry — `images` as `type: array` with a structure whose value is `{ src, alt }` and whose `_inputs` set `src` to `type: image` . See cc-friendly-conventions.md § Image galleries in MDX content.

常见说法	实际情况
“内置模板会处理这个问题”	验证往返行为。内置模板存在已知的边缘情况——请参阅 gotchas.md。
“我稍后会配置 snippet 工具栏”	没有工具栏，编辑者就无法插入 snippet。现在就在 `_editables` 中添加 `snippet: true` 。
“这个组件太冷门，不适合做 snippet”	如果编辑者会在内容中遇到它，就需要能够编辑它。请进行配置。
“内容中的 import 语句没问题”	使用 auto-import（Astro： `astro-auto-import` ），让 import 不出现在内容文件中。Hugo 和 Eleventy shortcode 不需要 import。
“这个我可以使用 `_snippets_imports` ”	不要这样做。它会加载 catchall matcher，可能会错误匹配。请编写显式的 `_snippets` 条目。只有通过 import 才能提供的预构建 snippet（Hugo 的内置 shortcode、Eleventy 的 `{% raw %}` ）属于例外——请按名称 include 它们。
“我配置了 `_snippets` ，snippet 已完成”	如果没有在 `astro.config.mjs` 中接入 `astro-auto-import` ，并从 MDX 文件中移除 `import` 行，编辑者仍会在 MDX 内容顶部看到原始 `import` 语句。管线的四个步骤缺一不可——请参阅 astro/overview.md § MDX 设置管线必须完成全部四个步骤。
“MDX 中的内联图片网格使用原始 HTML 没问题”	编辑者无法安全地编辑原始 `<div class="grid">` + `<Image>` 块。将其提取为自闭合的 `<Gallery images={[{src, alt}, ...]} />` 组件（自动导入），并添加匹配的 `_snippets` 条目——将 `images` 设置为 `type: array` ，其结构的值为 `{ src, alt }` ，并在 `_inputs` 中将 `src` 设置为 `type: image` 。请参阅 cc-friendly-conventions.md § MDX 内容中的图片库。

cloudcannon-snippets

Original

Translation

CloudCannon Snippets

CloudCannon Snippets

When to use

何时使用

When not to use

何时不应使用

Contents

目录

Quick decision

快速决策

Checklist

检查清单

Common mistakes

常见错误