Some documentation only applies to specific static site generators. To ensure the documentation is relevant for you, select your preferred SSG below:
Tip: You can change this at any time at the top right of the page.
Editing with Eleventy Snippets
Last modified: September 21st, 2023
CloudCannon supports embedding rich Snippets in Markdown content when using the CloudCannon Content Editor. Once configured, Snippets in your content will be presented as blocks in rich text views, with the ability to add them as Snippets via the toolbar:
To start configuring Snippets in your Eleventy content, a Snippet configuration must be imported using the _snippets_imports key in your CloudCannon global configuration file.
Currently, CloudCannon supports Snippets in the Nunjucks and Liquid templating languages, which can imported with the eleventy_nunjucks and eleventy_liquid keys:
CloudCannon provides support for the raw tag out of the box for both the eleventy_nunjucks and eleventy_liquid Snippet imports. If this isn't desired, you can exclude this snippet like so:
By default, CloudCannon will show the snippet toolbar action in the content editor if snippets are available.
If you have already customized which options are available via _editables in your CloudCannon config, you will need to include snippet: true for Snippets to be available. See the Editables options documentation for more details.
After importing the eleventy_liquid Snippets configurations, any custom liquid tags in your content will be displayed in the Content Editor as an Unknown Shortcode or Unknown shortcode pair. The same is true for eleventy_nunjucks and nunjuck tags. This allows an editor to move and delete a Snippet, but prevents editing of its arguments or content:
To enable editing and provide the custom Snippet in the toolbar, your custom Snippet must be configured using the _snippets object in your CloudCannon global config file. CloudCannon Snippets can be built from scratch to support nearly any syntax or SSG, but importing a Snippet configuration provides a set of snippet templates for common use cases in Eleventy.
To help illustrate configuring custom Snippets, we will first cover a few examples. First, let's look a custom tint Snippet on our Eleventy site that takes a string and applies a color to it:
The first thing we need to do is decide which Snippet template to use, which we can determine from the following aspects:
First, we want to configure this shortcode for the Nunjucks templating language
Next, this is an Eleventy "shortcode" rather than an "include" or other tag
Lastly, in Eleventy terms this is a "paired" shortcode, since it has a start and an end tag that wrap some content.
Looking at the list of snippet templates further down this page, this means we should configure this snippet using the eleventy_nunjucks_paired_shortcode_positional_args template. A full example configuration for this Snippet thus might look like the following:
Each snippet definition lives under a top level key, eleventy_tint in this example. This is the unique name that CloudCannon uses to identify this snippet, but is otherwise unused in the shortcode configuration itself.
We specify the template that this snippet should inherit from, and also specify that it is an inline snippet, since it can live anywhere in the content (such as in the middle of a sentence).
In definitions we need to specify some values that are required for the template we picked. For the eleventy_nunjucks_paired_shortcode_positional_args template, we need to specify:
The shortcode_name — in this case we're configuring our tint shortcode
The content_key — this controls the key that CloudCannon will use to edit the text in between the start and end tags of the shortcode.
The positional_args — for our tint shortcode we need to configure that the first argument should be captured with the key tint_color
Finally, we can specify any other keys from the CloudCannon configuration cascade here. In this example, we configure the inputs for the keys that this snippet will generate. With that in place, we can now add and edit our tint shortcode anywhere on our site.
Next, let's quickly look at a shortcode with a different syntax:
This time, we have an unpaired Liquid include that takes type and message argument keys. This syntax matches the eleventy_liquid_include template.
In CloudCannon, we could configure this snippet using the following global configuration:
This should now be familiar, but with a few changes:
We want this snippet to be a block-level element in the editor, so we set inline to false.
Since this include does not have an end tag, we have no content_key
Instead of positional_args, we now have named_args
Configuring named arguments uses most of the same options as the positional arguments earlier, but here we can additionally specify source_key and editor_key separately. In this example, we want the key in our shortcode to be type, but tell CloudCannon to treat that value as the label key, which we then configure using our inputs configuration.
The first step to configure your custom Snippet is to identify which Snippet template to use, as each Snippet template requires a set of definitions keys to be configured. The following Snippet templates are available:
A list of values that this argument must be in order to match this snippet definition. Allows you to match different usages of the same shortcode to separate snippet definitions based on the value of an argument.