Configure your rich text editors

You can configure your rich text editors to control which text and image formatting tools are available in the WYSIWYG toolbar, the upload paths or filenames for any assets uploaded through an editor, and how CloudCannon should handle custom markup.

There are multiple ways to configure your rich text editors, depending on which editor you want to configure: the Content Editor, Editable Regions in the Visual Editor, or Rich Text inputs.

For a complete list of options available for rich text editors, please read our rich text editor reference.

The Content Editor#

To configure your Content Editor:

1. Navigate to your global configuration file and open it in the Source Editor. CloudCannon will show the file contents for you to edit.
2. Identify the _editables key, or create one at the top level of your configuration file.
3. Add the content key under _editables.
4. Add any keys you want to configure under the content key.
5. Save your changes to the global configuration file.

CloudCannon will offer the controls you enabled in the WYSIWYG toolbar the next time you open a file in the Content Editor.

Let's walk through an example. We want to allow our Organization Members to be able to apply bold, italic, and underline formatting to text in the Content Editor. The global configuration file should look like this:

_editables:
  content:
    bold: true
    italic: true
    underline: true

{
  "_editables": {
    "content": {
      "bold": true,
      "italic": true,
      "underline": true
    }
  }
}

Rich Text inputs#

To configure your Rich Text inputs:

1. Navigate to your global configuration file and open it in the Source Editor. CloudCannon will show the file contents for you to edit.
2. Identify the _inputs key, or create one at the top level of your configuration file.
3. Enter the key name for your input under the _inputs key.
4. Add the options key under your input name.
5. Add any keys you want to configure under the options key.
6. Save your changes to the global configuration file.

CloudCannon will offer the controls you enabled in the WYSIWYG toolbar the next time you open a file containing that input.

_inputs:
  example:
    type: html
    options:
      bold: true
      italic: true
      underline: true

{
  "_inputs": {
    "example": {
      "type": "html",
      "options": {
        "bold": true,
        "italic": true,
        "underline": true
      }
    }
  }
}

Editable Regions#

The _editables key configures Editable Regions as well as the Content Editor. CloudCannon chooses which key applies from the HTML element your region sits on:

• text — paragraphs, headings, blockquotes, and list items: <p>, <h1> through <h6>, <blockquote>, <li>, <dd>, and <dt>
• block — sectioning elements: <div>, <section>, <article>, <aside>, <main>, <header>, <footer>, and <nav>
• link — <a> elements
• image — <img> elements

A Text Editable Region can override that lookup with the data-type attribute, which accepts span, text, or block. A region with data-type="block" takes its configuration from _editables.block whichever element it sits on. For more information, please read our documentation on configuring Text Editable Regions.

To configure your Editable Regions:

1. Navigate to your global configuration file and open it in the Source Editor. CloudCannon will show the file contents for you to edit.
2. Identify the _editables key, or create one at the top level of your configuration file.
3. Add the key for the type of Editable Region under _editables (i.e., text, block, link, or image⁠).
4. Add any keys you want to configure under the Editable Region key.
5. Save your changes to the global configuration file.

CloudCannon will offer the controls you enabled in the WYSIWYG toolbar the next time you open a file in the Visual Editor.

_editables:
  text:
    bold: true
    italic: true
    underline: true
  block:
    format: p h3
    undo: true
    redo: true
  link:
    paths:
      uploads: assets/links
  image:
    mime_type: image/png
    allowed_sources:
      - site-files

{
  "_editables": {
    "text": {
      "bold": true,
      "italic": true,
      "underline": true
    },
    "block": {
      "format": "p h3",
      "undo": true,
      "redo": true
    },
    "link": {
      "paths": {
        "uploads": "assets/links"
      }
    },
    "image": {
      "mime_type": "image/png",
      "allowed_sources": [
        "site-files"
      ]
    }
  }
}

On a class="editable" region, you can configure options directly on the element with a JSON value in the data-cms-options attribute instead. Editable Regions defined with data-editable attributes do not read data-cms-options, and take their configuration from _editables.

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

Text styles#

The styles key adds a Styles dropdown to the WYSIWYG toolbar, offering your Organization Members a named style for each rule in a CSS file you nominate. A style is the combination of an element and a class name, so a rule such as p.lead becomes an option your Organization Members can apply to a paragraph. Set the value to the path of the CSS file, either in your source files or in your build output.

styles is available on the Content Editor, on text and block Editable Regions, and on Rich Text inputs.

_editables:
  content:
    styles: /css/editor.css
  text:
    styles: /css/editor.css
_inputs:
  example:
    type: html
    options:
      styles: /css/editor.css

{
  "_editables": {
    "content": {
      "styles": "/css/editor.css"
    },
    "text": {
      "styles": "/css/editor.css"
    }
  },
  "_inputs": {
    "example": {
      "type": "html",
      "options": {
        "styles": "/css/editor.css"
      }
    }
  }
}

Text alignment#

Text alignment controls are available in the Content Editor, block Editable Regions, and Rich Text inputs. To enable them, add the align key to your rich text editor configuration and set each alignment you want to offer to true.

CloudCannon saves alignment as a text-align style on the block of text (e.g., <p style="text-align: center;">⁠). Use the default key to name the alignment your CSS already applies. Selecting the default alignment in the WYSIWYG toolbar removes any existing alignment from the block rather than saving a style for it.

_editables:
  content:
    align:
      default: left
      left: true
      center: true
      right: true
      justify: false

{
  "_editables": {
    "content": {
      "align": {
        "default": "left",
        "left": true,
        "center": true,
        "right": true,
        "justify": false
      }
    }
  }
}

If your site aligns text with class names rather than inline styles, add them under the classes key. CloudCannon will toggle the class name for each alignment instead of saving a text-align style. Any alignment without a class name falls back to the text-align style. Define the class names in the CSS file you set with the styles key so that the alignment is visible in the editor.

_editables:
  content:
    styles: /css/editor.css
    align:
      default: left
      left: true
      center: true
      right: true
      classes:
        left: align-left
        center: align-center
        right: align-right

{
  "_editables": {
    "content": {
      "styles": "/css/editor.css",
      "align": {
        "default": "left",
        "left": true,
        "center": true,
        "right": true,
        "classes": {
          "left": "align-left",
          "center": "align-center",
          "right": "align-right"
        }
      }
    }
  }
}

.align-left { text-align: left; }
.align-center { text-align: center; }
.align-right { text-align: right; }

The align key replaces the deprecated left, center, right, and justify keys, which each took a class name. Existing configuration using those keys continues to work. To migrate, move each class name under align.classes, set the matching alignment to true, and set default to left.