HTML

Manage content in HTML files.

HTML files can be opened in the Visual Editor, Data Editor and Source Editor. There are two ways to give your editors access to manage content in the HTML.

Editable Regions - Perfect for simple use cases where you want to make the contents of an HTML element editable.
Editor Links - Useful for managing complex content structures populated through front matter or data file.

Editable Regions

Editable Regions have yellow borders in the Visual Editor indicating what areas are updatable. Define large sections to give full control or limit access by defining select images and text elements. Depending on what element the editable is applied to, editors will see different options in the editor.

To define an Editable Region:

Identify the HTML element you want editable
Add class="editable" to the HTML element. If the element already has a class you can append the editable class, for example: <div class="content editable">

The Visual Editor supports JavaScript. However, HTML rendered with JavaScript is not editable.

Editor Links

Editor Links allow you to link to other sections of the CloudCannon interface from within the Visual Editor. Use them to create edit buttons for your collection items and blog posts that are not visible on your live site. You can also add front matter Editor Links to open the front matter Editor at specified fields.

Editor Links are prefixed with cloudcannon: and match the URL structure of the CloudCannon app, for example:

index.html

<a href="cloudcannon:collections/_staff/">
  Edit all staff
</a>

<a href="cloudcannon:collections/_staff/jane-doe.md">
  Edit Jane Doe
</a>

<a href="cloudcannon:collections/_posts/2015-07-30-welcome-post.md">
  Edit Welcome Post
</a>

<a href="cloudcannon:status">
  Link to Site Status and Recent Activity
</a>

index.html

<a href="cloudcannon:collections/data/staff/">
  Edit all staff
</a>

<a href="cloudcannon:collections/data/staff/jane-doe.md">
  Edit Jane Doe
</a>

<a href="cloudcannon:collections/content/posts/welcome-post.md">
  Edit Welcome Post
</a>

<a href="cloudcannon:status">
  Link to Site Status and Recent Activity
</a>

index.html

<a href="cloudcannon:collections/staff/">
  Edit all staff
</a>

<a href="cloudcannon:collections/staff/jane-doe.md">
  Edit Jane Doe
</a>

<a href="cloudcannon:collections/posts/welcome-post.md">
  Edit Welcome Post
</a>

<a href="cloudcannon:status">
  Link to Site Status and Recent Activity
</a>

Front matter Editor Links are prefixed with cloudcannon:# and use a common syntax to reference them, for example:

index.html

<!-- Inputs -->
<a href="cloudcannon:#title">
  Edit the title
</a>

<!-- Arrays -->
<a href="cloudcannon:#array[1]">
  Edit the first array item
</a>

<a href="cloudcannon:#array[+]">
  Create a new item in an array
</a>

<!-- Inputs within an Object -->
<a href="cloudcannon:#object.title">
  Edit a variable within an object
</a>

<a href="cloudcannon:#object.array">
  Edit an array within an object
</a>

<!-- Inputs within an Array inside an Object -->
<a href="cloudcannon:#object.array[0].title">
  Edit the title of the first array item within an object
</a>

Instead of only anchor tags, any element can have an Editor Link by using the data-cms-editor-link attribute, for example:

index.html

<h1 data-cms-editor-link="cloudcannon:#title">
  HTML
</h1>

Posts

To have edit links for posts in a list, add an Editor Link in the blog post loop:

posts.html

<ul class="blog-posts">
  {% for post in site.posts %}
    <li class="blog-post">
      <h3>{{ post.title }}</h3>
      <p>{{ post.excerpt }}</p>
      <a href="{{ post.url }}">Read more</a>

      <!-- Editor Link -->
      <a href="cloudcannon:collections/{{ post.path }}" class="editor-link">Edit post</a>
    </li>
  {% endfor %}
</ul>

posts.html

<ul class="blog-posts">
  {{ range .Pages }}
    <li class="blog-post">
      <h3>{{ .Title }}</h3>
      <p>{{ .Summary }}</p>
      <a href="{{ .RelPermalink }}">Read more</a>

      <!-- Editor Link -->
      <a href="cloudcannon:/collections/content/{{ .File.Path }}" class="editor-link">Edit post</a>
    </li>
  {{ end }}
</ul>

posts.njk

<ul class="blog-posts">
  {% for post in collections.posts %}
    <li class="blog-post">
      <h3>{{ post.title }}</h3>
      <p>{{ post.excerpt }}</p>
      <a href="{{ post.url }}">Read more</a>

      <!-- Editor Link -->
      <a href="cloudcannon:collections/{{ post.inputPath | replace('./', '') }}" class="editor-link">Edit post</a>
    </li>
  {% endfor %}
</ul>

Screenshot of visual editor with editor links to edit blog posts

Collection Items

To have an edit link on a collection item page, add the following to the page:

item.html

<a href="cloudcannon:collections/{{ page.relative_path }}" class="editor-link">Edit</a>

If you are using a custom collections_dir include site.collections_dir in your editor link:

item.html

<a href="cloudcannon:collections/{{ site.collections_dir }}/{{ page.relative_path }}" class="editor-link">Edit</a>

Note

When generating Editor Links in Jekyll, collection items should use relative_path, while posts and pages should use path.

item.html

<a href="cloudcannon:collections/content/{{ .File.Path }}" class="editor-link">Edit</a>

replace ‘content’ in the href with the name of your content directory.

item.njk

<a href="cloudcannon:collections/{{ page.inputPath | replace('./', '') }}" class="editor-link">Edit</a>

Toggling Visibility

To show Editor Links inside the editor and hide them on the live site:

Give the links an appropriate class name (e.g. .editor-link).
Use the following CSS to show the links inside the editor only:

styles.css

.editor-link {
  display: none;
}

.cms-editor-active .editor-link {
  display: block;
}

Note

CloudCannon adds the .cms-editor-active class to the body of your site in the Visual Editor. The class is not on the live site.

Editor Link Behavior

Front matter can be highlighted within the sidebar or displayed standalone in a modal popup. To change how an editor link opens:

Add the data-cms-editor-link-style attribute
Set the attribute’s value to modal or sidebar (optional)

index.html

<a href="cloudcannon:#title" data-cms-editor-link-style="modal">
  Edit the title
</a>

<h1 data-cms-editor-link="cloudcannon:#title" data-cms-editor-link-style="modal">
  HTML
</h1>

Note

Using modal-style editor links that point directly to hidden fields show the field in the pop up.

Styling

You can give Editor Links our default styles by adding the cms-editor-link class. This provides a seamless experience alongside Editable Regions by using the same styles.

index.html

<a href="cloudcannon:#title" class="cms-editor-link">
  Edit the title
</a>

<h1 data-cms-editor-link="cloudcannon:#title" class="cms-editor-link">
  HTML
</h1>

Note

cms-editor-link-dirty is also handled with the default styles.

Default Editor Path

Set the default path to load when the Update Home action is clicked in the Dashboard.

These options are set in _config.yml on the top level. For example:

_config.yml

_editor:
  default_path: /about/

These options are set in your site config on the top level. For example:

config.toml

[_editor]
default_path = "/about/"

These options are set in your _data/cloudcannon.* file. For example:

_data/cloudcannon.js

module.exports = {
  _editor: {
    default_path: '/about/'
  }
};

Clicking the Update Home dashboard action loads the default_path. The example above loads /about/ rather than the default /.

Overview

Markdown

Don’t miss the latest

CloudCannon news freshly delivered to your inbox

Illustration of woman holding an envilope