---
name: cloudcannon-snippets
description: >-
  Use when adding snippet support to a CloudCannon site, configuring MDX
  components, Hugo shortcodes or Eleventy shortcodes and includes for the
  Content Editor, debugging snippet round-trip issues, or setting up inline
  HTML snippets in markdown content.
---

# 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, 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

## 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`](../cloudcannon-configuration/SKILL.md) and the migration skill's page-building guide.
- **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.
- **Plain markdown content with no components or inline HTML** — no snippet configuration is needed

## Contents

| Doc                                            | When to read                                                                                                                                             |
| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [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 |
| [template-based.md](template-based.md)         | Component syntax matches a built-in template (most common path)                                                                                          |
| [raw.md](raw.md)                               | Component needs custom syntax (e.g. `client:load`, non-standard attributes)                                                                              |
| [built-in-templates.md](built-in-templates.md) | Understanding built-in MDX, Hugo and Eleventy templates, the import bundle, parser internals                                                             |
| [gotchas.md](gotchas.md)                       | Preventative rules — the pitfalls and their workarounds                                                                                                  |
| [troubleshooting.md](troubleshooting.md)       | Symptom index — start here when something is already broken, it routes to the rule                                                                       |

**SSG-specific:**

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

## Quick decision

| Case                                                           | Approach                                                                                                                                 |
| -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Component syntax matches a built-in template                   | Template-based — see [template-based.md](template-based.md)                                                                              |
| Extra syntax, SSG directives, custom parsing                   | Raw — see [raw.md](raw.md)                                                                                                               |
| 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)                    |
| 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?](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.

## 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)

## Common mistakes

| Excuse                                         | Reality                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "The built-in templates handle this"           | Verify the round-trip. Built-in templates have known edge cases — see [gotchas.md](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](astro/overview.md#mdx-setup-pipeline-must-complete-all-four).                                                                                                                                                                  |
| "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](../migrate-to-cloudcannon/astro/cc-friendly-conventions.md#image-galleries-in-mdx-content). |