Configure your rich text editors

Working with a specific static site generator?
Customize CloudCannon's documentation to suit your SSG.

Great! We'll show you documentation relevant to .
You can change this any time using the dropdown in the navigation bar.

Editable Regions are configured with the _editables option within the configuration cascade. The following keys are available within _editables:

text for simple block editable regions like (e.g. <p>)
block for block editable regions (e.g. <div> or <section>)
link for inline editable regions on <a> tags
image for image editable regions (i.e. <img>)
content for the main content section of the Content Editor.

Alternatively, you can configure options directly on the element with a JSON value in the data-cms-options attribute.

page.html

copied

<p class="editable" data-cms-options='{ "bold": true }'>
  ...
</p>

cloudcannon.config.yaml

copied

_editables:
  text:
    italic: true
  block:
    format: p h3
    undo: true
    redo: true
  content:
    blockquote: true
    bold: true
    format: p h1 h2 h3 h4 h5 h6 pre address div
    italic: true
    strike: true
    subscript: true
    superscript: true
    underline: true
    link: true
    bulletedlist: true
    indent: true
    numberedlist: true
    outdent: true
    code: true
    embed: true
    horizontalrule: true
    image: true
    table: true
    undo: true
    redo: true
    removeformat: true
    copyformatting: true
    styles: /css/editor.css
    left: align-left
    center: align-center
    right: align-right
    justify: align-justify
    image_size_attributes: true
    snippet: true

cloudcannon.config.json

copied

{
  "_editables": {
    "text": {
      "italic": true
    },
    "block": {
      "format": "p h3",
      "undo": true,
      "redo": true
    },
    "content": {
      "blockquote": true,
      "bold": true,
      "format": "p h1 h2 h3 h4 h5 h6 pre address div",
      "italic": true,
      "strike": true,
      "subscript": true,
      "superscript": true,
      "underline": true,
      "link": true,
      "bulletedlist": true,
      "indent": true,
      "numberedlist": true,
      "outdent": true,
      "code": true,
      "embed": true,
      "horizontalrule": true,
      "image": true,
      "table": true,
      "undo": true,
      "redo": true,
      "removeformat": true,
      "copyformatting": true,
      "styles": "/css/editor.css",
      "left": "align-left",
      "center": "align-center",
      "right": "align-right",
      "justify": "align-justify",
      "image_size_attributes": true,
      "snippet": true
    }
  }
}

cloudcannon.config.cjs

copied

module.exports = {
  _editables: {
    text: {
      italic: true
    },
    block: {
      format: "p h3",
      undo: true,
      redo: true
    },
    content: {
      blockquote: true,
      bold: true,
      format: "p h1 h2 h3 h4 h5 h6 pre address div",
      italic: true,
      strike: true,
      subscript: true,
      superscript: true,
      underline: true,
      link: true,
      bulletedlist: true,
      indent: true,
      numberedlist: true,
      outdent: true,
      code: true,
      embed: true,
      horizontalrule: true,
      image: true,
      table: true,
      undo: true,
      redo: true,
      removeformat: true,
      copyformatting: true,
      styles: "/css/editor.css",
      left: "align-left",
      center: "align-center",
      right: "align-right",
      justify: "align-justify",
      image_size_attributes: true,
      snippet: true
    }
  }
};

Although this is example sets the options globally, you can set this on different scopes in the configuration cascade.

page.html

copied

<p data-cms-options='{"bold": true, "italic": true}'
  class="editable"></p>

Formatting#

Options for base text formatting.

blockquote - Boolean#

Enables a control to wrap blocks of text in block quotes.

Available for _editables.block and _editables.content.

bold - Boolean#

Enables a control to set selected text to bold.

Available for _editables.text, _editables.block and _editables.content.

format - String#

Enables a drop down menu for structured text. Has options for p, h1, h2, h3, h4, h5, h6, pre, address, and div. Set as space separated options, e.g. format: p h1 h2.

Available for _editables.block and _editables.content.

italic - Boolean#

Enables a control to italicize selected text.

Available for _editables.text, _editables.block and _editables.content.

strike - Boolean#

Enables a control to strike selected text.

Available for _editables.text, _editables.block and _editables.content.

subscript - Boolean#

Enables a control to set selected text to subscript.

Available for _editables.text, _editables.block and _editables.content.

superscript - Boolean#

Enables a control to set selected text to superscript.

Available for _editables.text, _editables.block and _editables.content.

underline - Boolean#

Enables a control to underline selected text.

Available for _editables.text, _editables.block and _editables.content.

link - Boolean#

Enables a control to create hyperlinks around selected text.

Available for _editables.text, _editables.block and _editables.content.

List controls#

Options for managing text in lists and nested lists.

bulletedlist - Boolean#

Enables a control to insert an unordered list, or to convert selected blocks of text into a unordered list.

Available for _editables.block and _editables.content.

indent - Boolean#

Enables a control to increase indentation for numbered and unordered lists.

Available for _editables.block and _editables.content.

numberedlist - Boolean#

Enables a control to insert a numbered list, or to convert selected blocks of text into a numbered list.

Available for _editables.block and _editables.content.

outdent - Boolean#

Enables a control to reduce indentation for numbered and unordered lists.

Available for _editables.block and _editables.content.

Block content#

Options for adding media and full-width content elements.

code - Boolean#

Enables a control to set selected text to inline code, and unselected blocks of text to code blocks.

Available for _editables.block and _editables.content.

embed - Boolean#

Enables a control to insert a region of raw HTML, including YouTube, Vimeo, Tweets, and other media. Embedded content is sanitized to mitigate XSS risks, which includes removing style tags. Embeds containing script tags are not loaded in the editor.

Available for _editables.block and _editables.content.

horizontalrule - Boolean#

Enables a control to insert a horizontal rule.

Available for _editables.block and _editables.content.

image - Boolean#

Enables a control to insert an image. The image can be uploaded, existing or an external link.

Available for _editables.block and _editables.content.

table - Boolean#

Enables a control to insert a table. Further options for table cells are available in the context menu for cells within the editor.

Available for _editables.block and _editables.content.

snippet - Boolean#

Enables a control to insert snippets, if any are available. See Editing with Hugo Shortcodes/

Available for _editables.block and _editables.content.

Image options#

Options for images when enabled.

image_size_attributes - Boolean#

Instructs the editor to save width and height on the image elements added to this editable. This can prevent pop-in as a page loads. Defaults to false.

This defaults to true for sites created before June 23 2023, in order to keep those sites working. Use the Image Size Attributes Default flag to update this for your site, if needed.

Available for _editables.image, _editables.block and _editables.content.

width - Integer#

Defines the width of the bounding box used in the resizing process defined with resize_style.

Available for _editables.image, _editables.block and _editables.content.

height - Integer#

Defines the height of the bounding box used in the resizing process defined with resize_style.

Available for _editables.image, _editables.block and _editables.content.

resize_style - String#

Sets how uploaded image files are resized with a bounding box defined by width and height prior to upload. Defaults to contain. Must be contain, cover or stretch:

cover keeps aspect ratio and ensures the image covers the bounding box
contain keeps aspect ratio and ensures the image fits inside the bounding box
stretch ignores aspect ratio and resizes the image to the bounding box

Has no effect when selecting existing images, or if width and height are not set.

Available for _editables.image, _editables.block and _editables.content.

mime_type - String#

Sets what format the image is converted to prior to upload. The extension of the file is updated to match. Defaults to keeping the mime type of the uploaded file. Must be one of image/jpeg or image/png.

Available for _editables.image, _editables.block and _editables.content.

expandable - Boolean#

Controls whether or not images can be upscaled to fit the bounding box during resize prior to upload. Defaults to false. Has no effect if files are not resized.

Available for _editables.image, _editables.block and _editables.content.

allowed_sources - Array#

If you have one or more DAMs connected to your site, you can use this key to list which asset sources can be uploaded to and selected from.

You can refer to a DAM with the Reference Key field from the site-level DAM configuration.

You can refer to your site files with site-files. If this is omitted from the array, site files will not be available as an asset source for this input.

Actions#

Options for editor actions when editing and formatting content.

undo - Boolean#

Enables a control to undo recent edits. Undo is always enabled through standard OS-specific keyboard shortcuts.

Available for _editables.text, _editables.block and _editables.content.

redo - Boolean#

Enables a control to redo recent edits undone with undo. Redo is always enabled through standard OS-specific keyboard shortcuts.

Available for _editables.text, _editables.block and _editables.content.

removeformat - Boolean#

Enables the control to remove formatting from text. Applies to formatting from bold, italic, underline, strike, subscript, and superscript. Does not remove other styles or formatting.

Available for _editables.text, _editables.block and _editables.content.

copyformatting - Boolean#

Enables a control to copy formatting from text to other text. Only applies to formatting from bold, italic, underline, strike, subscript, and superscript. Does not copy other styles or formatting.

Available for _editables.text, _editables.block and _editables.content.

Paths#

These paths control where new asset files are uploaded to. They also set the default path when choosing existing images, and linking to existing files.

paths - Object#

Paths to common folders. Each path is relative to global site source. If unset, the paths default to those configured in the global configuration. The available keys are:

uploads for the default location of newly uploaded site files.
dam_uploads for the default location of newly uploaded DAM files.
dam_static for the location of statically copied assets for DAM files.

uploads and dam_uploads have a number of dynamic placeholders available.

Available for _editables.link, _editables.text, _editables.image,_editables.block and _editables.content.

Styles and alignment#

Add predefined styles in plain CSS for your clients and team members to use in the Visual Editor and Content Editor.

styles - String#

Enables a drop down menu for editors to style selected text or blocks or text. Styles are the combination of an element and class name. The value for this option is the path (either source or build output) to the CSS file containing the styles.

Available for _editables.block and _editables.content.

left - String#

Enables a control to left align text by toggling a class name for a block of text. The value is the class name the editor should add to align the text. The styles for this class need to be listed in the styles file to take effect outside of the Visual Editor.

Available for _editables.block and _editables.content.

center - String#

Enables a control to center align text by toggling a class name for a block of text. The value is the class name the editor should add to align the text. The styles for this class need to be listed in the styles file to take effect outside of the Visual Editor.

Available for _editables.block and _editables.content.

right - String#

Enables a control to right align text by toggling a class name for a block of text. The value is the class name the editor should add to align the text. The styles for this class need to be listed in the styles file to take effect outside of the Visual Editor.

Available for _editables.block and _editables.content.

justify - String#

Enables a control to justify text by toggling a class name for a block of text. The value is the class name the editor should add to justify the text. The styles for this class need to be listed in the styles file to take effect outside of the Visual Editor.

Available for _editables.block and _editables.content.

The styles CSS file can be either a source or output file. The source CSS file is used if both exist. In either case, it must contain plain CSS.

Selectors must specify an element and one class in order to be included in the styles drop down. Styles with incompatible selectors are applied to the editor, but not shown as options.

The alignment classes for left, right, center and justify must be defined in the styles CSS file to give the editor access to those styles.

css/editor.css

copied

/* Can be applied to blocks of content */
p.callout {
  margin: 10px;
  border: 1px solid #f5f5f5;
  background-color: #eee;
}

/* Can be applied to inline content */
span.big-blue-text {
  font-size: 2rem;
  color: blue;
}

/* Applied to content, excluded from style dropdown */
h2 {
  font-family: cursive;
}

/* Applied to content, excluded from style dropdown */
.align-left { text-align: left; }
.align-center { text-align: center; }
.align-right { text-align: right; }
.align-justify { text-align: justify; }

Custom styles in the Visual Editor require the same styles on your live site. If you don’t have the same styles on your live site, the class will be there but it won’t change the styling.

Custom markup#

More options for handling HTML or Markdown structure that cannot be recreated in the rich text editor.

allow_custom_markup - Boolean#

Enables you to edit custom markup in rich text editors and explicitly accept the risk of unintentionally deleting elements that cannot be recreated. By default, allow_custom_markup is false for inputs and true for editable regions.

When using allow_custom_markup outside of editable regions, content that uses JavaScript will not be editable for security reasons. These inputs will appear as uneditable snippets.

For more information, please read our documentation on best practices for HTML in rich text and editable regions.

remove_custom_markup - Boolean#

Enables you to strip custom markup from content edited in a rich text editor, allowing you to clean files of unnecessary HTML content. By default, remove_custom_markup is false for inputs and editable regions.

The remove_custom_markup key is disabled if allow_custom_markup is enabled.

For more information, please read our documentation on best practices for HTML in rich text and editable regions.

Configure your rich text editors

Formatting#

List controls#

Block content#

Image options#

Actions#

Paths#

Styles and alignment#

Custom markup#

Related Articles