It’s only been a few weeks since we first introduced Snippets on CloudCannon, and they’re already saving time for CloudCannon developers, as well as for content teams collaborating on static sites. Today we’ll go through exactly what a Snippet is and how it can save you time on your next web project.
A Snippet is CloudCannon's method of configuring and then editing content with a wide range of structured components across different static site generators. With Snippets, content editors can use a simple interface to easily insert includes, shortcodes and Markdown extensions into their content — all without touching the underlying code.
You’ll see these terms used differently in different places around the web. Typically a static site generator will use the term ‘shortcode’ — Hugo and Eleventy both do this — to mean a relatively simple way to insert reusable content into an existing template. Some shortcodes are paired, meaning they require a closing tag, and can nest other template content inside them.
Includes, by contrast, allows you to ‘include’ or insert content onto your page from another file in your site structure. For instance, your site’s navigation, section titles and footer are best served from a single source of truth, so using includes is the most efficient and error-proof way to do so.
CloudCannon’s term Snippets is a superset, an umbrella term that covers a range of ways that static site generators use structured components. This encompasses includes in Eleventy, shortcodes in Hugo and Eleventy, and — coming soon — Markdown extensions in MkDocs and includes in Jekyll, among others. We support a wide range of SSGs, each with unique configuration requirements, but with Snippets we can support a range of different shortcodes, extensions, and includes across different SSGs, all configured in our global configuration file — allowing CloudCannon users to edit and develop more efficiently.
With Snippets, content writers can make use of reusable components within the Content or Visual Editors without having to switch over to raw HTML or Markdown — whether their task is embedding a correctly styled social media post into a page, adding navigation links between documentation pages, or any other specific repeatable content they need to do their jobs.
One of the main reasons that developers on CloudCannon use Snippets — and, let’s be honest, one of the main reasons developers use any tool — is to save time. By configuring and using Snippets, developers can avoid having to write out entire blocks of code from scratch, which can be time-consuming and error-prone, particularly when a built site is handed over to a content team for ongoing content loading.
As always, we focus on giving everyone the tools they need to work without getting in their way. Hence the simple Snippets button you’ll see in your Markdown editing menu:
After choosing which Snippet to add, all you’ll need to do is fill in the relevant fields, and your new content block is inserted directly into your Markdown. Here’s the process of adding a Snippet that uses one of Hugo’s built-in shortcodes:
Speaking as a writer and content editor, a GUI like this means I can spend more time actually seeing and thinking about the content I’m working on. (And the sooner I can see my content in its final context, the sooner I can make it better — which is why CloudCannon’s Visual Editor and Content Editor are my two most frequently used views.) Snippets are another part of the solution, and added to Bookshop components, there’s a really clear path to creating new pages (and entirely new sites) in a fraction of the time it would otherwise have taken.
Of course, having a GUI means configuring your Snippets ahead of time. Luckily, when it comes to configuring which Snippets are available for content teams to use, CloudCannon has you covered.
We go into a lot more detail on configuring Snippets for Hugo shortcodes and for Eleventy shortcodes in our documentation, but here’s a quick checklist of the minimum steps needed.
For Eleventy sites, in the global configuration file
cloudcannon.config.yml, you’ll need to:
_snippets_importskey. (This step is not required for built-in Hugo shortcodes, which are already imported.)
For both Hugo and Eleventy sites, In the global configuration file
cloudcannon.config.yml you’ll need to:
For example, setting up a custom Snippet for Hugo would look like this:
- editor_key: tint_color
comment: This text will be tinted
By default, when Snippets are available for either Hugo or Eleventy sites, CloudCannon will automatically add the Snippets button to your editing toolbar. (If you’ve already set custom editing options in your global configuration via the
_editables object, then you’ll need to include
snippets: true as well.)
Looking through our Snippets documentation, you’ll find a full list of all supported options to configure your custom shortcodes as a CloudCannon Snippet. If you have components that don’t fit our existing Snippet configuration, let us know! We’re still building out the Snippets feature, and while we have pretty clear plans, our development process is guided by user requests.
We’re also happy to help you configure your Snippets — just reach out to us in support and we’ll get back to you as soon as we can.
Jaimie McMahon · 16 May 2023
David Large · 5 May 2023
David Large · 28 Apr 2023