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).
When to use
- Adding snippet support to a new or existing CloudCannon site
- Configuring MDX components for the Content Editor
- Adding inline HTML snippets (figure, video, details) to markdown content
- Debugging snippet parsing, round-trip, or toolbar issues
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
Contents
| 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 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 |
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 |
Most setups use template-based for simple components and raw for anything with SSG-specific directives.
Checklist
Read this before starting and verify every item when done.
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. |
"I can use _snippets_imports for this" |
Don't. It loads catchall matchers that can match incorrectly. Write explicit _snippets entries. |
"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 nested images[*].src: type: image. See cc-friendly-conventions.md § Image galleries in MDX content. |
1---2name: cloudcannon-snippets3description: Use when adding snippet support to a CloudCannon site, configuring MDX components for the Content Editor, debugging snippet round-trip issues, or setting up inline HTML snippets in markdown content.4---56# CloudCannon Snippets78Snippets 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).910## When to use1112- Adding snippet support to a new or existing CloudCannon site13- Configuring MDX components for the Content Editor14- Adding inline HTML snippets (figure, video, details) to markdown content15- Debugging snippet parsing, round-trip, or toolbar issues1617## When not to use1819- **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`](../cloudcannon-configuration/SKILL.md) and the migration skill's page-building guide.20- **Making an existing rendered element editable in place** — that is [`cloudcannon-visual-editing`](../cloudcannon-visual-editing/SKILL.md). Snippets insert new markup; editable regions edit markup already on the page.21- **Plain markdown content with no components or inline HTML** — no snippet configuration is needed2223## Contents2425| Doc | When to read |26| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |27| [snippets.md](snippets.md) | Start here. Overview of both layers, configuration hierarchy, which approach to use, snippet properties, toolbar setup, raw HTML snippets in `.md` files |28| [template-based.md](template-based.md) | Component syntax matches a built-in template (most common path) |29| [raw.md](raw.md) | Component needs custom syntax (e.g. `client:load`, non-standard attributes) |30| [built-in-templates.md](built-in-templates.md) | Understanding built-in MDX templates, the import bundle, parser internals |31| [gotchas.md](gotchas.md) | Preventative rules — the pitfalls and their workarounds |32| [troubleshooting.md](troubleshooting.md) | Symptom index — start here when something is already broken, it routes to the rule |3334**SSG-specific:**3536| SSG | Doc |37| ----- | ----------------------------------------------------------------------------------------------- |38| Astro | [astro/overview.md](astro/overview.md) — MDX stack, `astro-auto-import`, when to use MDX vs raw |3940## Quick decision4142| Case | Approach |43| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |44| Component syntax matches a built-in template | Template-based — see [template-based.md](template-based.md) |45| Extra syntax, SSG directives, custom parsing | Raw — see [raw.md](raw.md) |46| Inline HTML in `.md` (`<figure>`, `<video>`) | Raw snippets — see [snippets.md § Raw snippets for inline HTML](snippets.md#raw-snippets-for-inline-html-in-md-files) |4748Most setups use template-based for simple components and raw for anything with SSG-specific directives.4950## Checklist5152Read this before starting and verify every item when done.5354- [ ] Every component used in content files has a `_snippets` entry55- [ ] `_editables` includes `snippet: true` on relevant content blocks56- [ ] Each snippet round-trips correctly (insert via editor, save, reopen — markup unchanged)57- [ ] `_inputs` are configured for snippet fields (image fields get `type: image`, etc.)58- [ ] Snippet previews are configured (`view: gallery` for image-bearing snippets)59- [ ] `picker_preview` uses static values (not `key:` lookups, which don't resolve in picker context)6061## Common mistakes6263| Excuse | Reality |64| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |65| "The built-in templates handle this" | Verify the round-trip. Built-in templates have known edge cases — see [gotchas.md](gotchas.md). |66| "I'll configure the snippet toolbar later" | No toolbar means editors can't insert snippets. Add `snippet: true` to `_editables` now. |67| "This component is too niche for a snippet" | If editors encounter it in content, they need to be able to edit it. Configure it. |68| "Import statements in content are fine" | Use auto-import (Astro: `astro-auto-import`) to keep imports out of content files. |69| "I can use `_snippets_imports` for this" | Don't. It loads catchall matchers that can match incorrectly. Write explicit `_snippets` entries. |70| "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](astro/overview.md#mdx-setup-pipeline-must-complete-all-four). |71| "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 nested `images[*].src: type: image`. See [cc-friendly-conventions.md § Image galleries in MDX content](../migrate-to-cloudcannon/astro/cc-friendly-conventions.md#image-galleries-in-mdx-content). |
cloudcannon