Fine tuning the editing experience

Hugo CMS - Get started with CloudCannon

CloudCannon provides basic content editing without any configuration. To get the most out of the platform, you have full control to fine-tune the editing experience. CloudCannon configuration typically lives in a global config file but can also be set at a variety of scopes.

Let’s set up the global config file. Create cloudcannon.config.yml in the source directory (probably the root unless you have a custom setup) of your website. We’ll use this file throughout the rest of this tutorial.

There are four main ways to structure content on a Hugo site, let’s walk through how they work on CloudCannon:

Markdown

Content sourced from Markdown will editable in the Visual Editor by default as long as it’s wrapped in an HTML element. For example, this would be editable in the Visual Editor:

<div class="content">
  {{ .Content }}
</div>

This would not:

<div class="content">
  {{ .Content }}
  <p>I'm not an only child</p>
</div>

Read more about this in the Editing Markdown files in Visual Editor docs.

You can also edit Markdown content on CloudCannon with the Content Editor, and in the front matter with the Data Editor.

The two things you may want to configure for Markdown content is your Markdown engine, and the WYSIWYG toolbar in both the Visual and Content Editor.

Let’s go over an example of how you would customize the toolbar. Say we want to give our content team the ability to add a table to Markdown files. In our global config file we have full control over all the editing WYSIWYG toolbar.

cloudcannon.config.yml

_editables:
  content:
    bold: true
    italic: true
    bulletlist: true
    numberedlist: true
    image: true
    table: true
    undo: true
    redo: true

This example scratches the surface of how you can configure the WYSIWYG toolbar. Check out the docs for a full list of options.

HTML

HTML lives in layouts on a Hugo site. You can add a class of editable to most HTML element to make it editable in the Visual Editor. For example:

layouts/home.html

<p class="editable">I'm editable in the visual editor</p>
<p>I'm <strong>not</strong> editable in the visual editior</p>

Give as much or as little access to your content team as they need. Just note, changes to the HTML save back to the layout which might be used by multiple content files.

The element you apply the editable class to will change what editing options are available in the WYSIWYG toolbar. For example, add the editable class to an <h1> and you’ll get basic text formatting options. Add it to a <div> and you’ll also be able to add images, lists, and tables. You can even customize the WYSIWYG toolbar to have complete control over what editors can and cannot add to each element.

HTML content can only be updated in the Visual Editor.

Front Matter

Content in front matter is automatically available in the sidebar in both the Visual Editor and Content Editor, as well as on its own in the Data Editor. You can customize every property to provide the best editing interface for your content team.

CloudCannon has naming conventions that do not require any further configuration. For example, if you end a front matter field with _image, like background_image, CloudCannon will display a image upload/selector. There’s a number of these conventions you can learn more about in the Customizing your inputs documentation.

You can also explicitly configure a front matter field too. For example, let’s say you had the following front matter:

index.html

---
background: "#ff0000"
hero_content: "Everything you need"
sidebar: 
---

And we wanted editors to have the following inputs for each one:

background - color picker
hero_content - WYSIWYG markdown editor
sidebar - checkbox

We could add the following to the global configuration file:

cloudcannon.config.yml

_inputs:
  background:
    type: color
  hero_content:
    type: markdown
  sidebar:
    type: checkbox

Here’s some of the input types available:

On top of configuring the type of input, you can configure how it displays and behaves in CloudCannon:

Comment — Add a description to help your editors understand how to use this field.
Instance Value — Initialize a field with a unique UUID or today’s date.
Hidden — Hide a field you don’t want your content team to change.
Label — The label for the input.

Let’s add some of these fields to the input configuration we defined previously:

cloudcannon.config.yml

_inputs:
  background:
    type: color
    comment: "Defines the background for the entire page"
  hero_content:
    type: markdown
    label: "Hero text"
  sidebar:
    type: checkbox
    hidden: true

If you want to update front matter content in the Visual Editor rather than the sidebar, you can set up Visual Data binding, which is a small snippet of HTML in your layout to tell CloudCannon which front matter property populates the HTML element. For example,

<h1 data-cms-bind="#title">Main Heading</h1>

will open an overlay to edit the title property in front matter.

Page Building

A popular and powerful way to empower content editors is to provide them with a set of building blocks or page components and let them add, remove, reorder, and update these components to build their own pages.

CloudCannon Structures support a set of predefined objects. For example, you might have a structure that allows editors to add photo galleries, testimonials, image and text blocks, and CTAs. It makes them a perfect fit for creating your own page builder. You define the content structures you want for editors, and they can add, remove, reorder, and update them from the array.

When you pair Structures with visual data binding and visual data previews, you have a powerful page builder which behaves in a similar way to Squarespace. This is extremely powerful but can take some configuration to set up, so we’ve created Bookshop to automate this process. It’s an open-source component library for Hugo and other SSGs. It’s simple to set up and has tight integration into CloudCannon, which will handle the majority of the setup.

To get started with Bookshop, take a look at the Hugo starter guide or a full tutorial on converting Bootstrap to Hugo + Bookshop.

Data files

Data files are automatically available to update in the Data Editor. The same inputs configuration you used for front matter will work on data files too.

Editing interfaces

Collaborating with your team