Rich text editor reference

Rich text editors are editing interfaces that enable you to create and format content. Rich text editors are WYSIWYG editors, so the content you create will look like it does on your web page. CloudCannon has three kinds of rich text editors: the Content Editor, editable regions in the Visual Editor, and Rich Text inputs.

This article covers all keys available in CloudCannon for configuring your rich text editors. For more information, please read our documentation on rich text editors in general, configuring rich text editors, and best practices for custom markup in rich text.

Not all WYSIWYG tools are available for every rich text editor.

Text options#

The following options are available in the WYSIWYG toolbar for text formatting:

cloudcannon.config.yaml

copied

_editables:
  content:
    blockquote: true
    bold: true
    format: p h1 h2 h3 h4 h5 h6 pre address div
    italic: true
    link: true
    strike: true
    subscript: true
    superscript: true
    underline: true

cloudcannon.config.json

copied

{
  "_editables": {
    "content": {
      "blockquote": true,
      "bold": true,
      "format": "p h1 h2 h3 h4 h5 h6 pre address div",
      "italic": true,
      "link": true,
      "strike": true,
      "subscript": true,
      "superscript": true,
      "underline": true
    }
  }
}

blockquote — Boolean#

This key enables a tool to wrap selected blocks of text in a block quote.

Available for the Content Editor (_editables.content), the Block editable region (_editables.block), the Link editable region (_editables.link), and Rich Text inputs (_inputs.key_name.options).

bold — Boolean#

This key enables a tool to bold selected text.

Available for the Content Editor (_editables.content), the Block editable region (_editables.block), the Link editable region (_editables.link), the Text editable region (_editables.text), and Rich Text inputs (_inputs.key_name.options).

format — String#

This key enables a dropdown menu tool for structured text. Valid values include for p, h1, h2, h3, h4, h5, h6, pre, address, and div. Include a space between each values, e.g. format: p h1 h2.

italic — Boolean#

This key enables a tool to italicize selected text.

link — Boolean#

This key enables a tool to create a hyperlink around selected text.

strike — Boolean#

This key enables a tool to strike through selected text.

subscript — Boolean#

This key enables a tool to subscript selected text.

superscript — Boolean#

This key enables a tool to superscript selected text.

underline — Boolean#

This key enables a tool to underline selected text.

Style and alignment options#

The following options are available in the WYSIWYG toolbar for text style and alignment:

cloudcannon.config.yaml

copied

_editables:
  content:
    styles: /css/editor.css
    left: align-left
    center: align-center
    right: align-right
    justify: align-justify

cloudcannon.config.json

copied

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

styles — String#

This key enables a dropdown menu to apply a style to selected text. Styles are the combination of an element and class name. The value for this option is the path (either source or build output) for the CSS file containing styles.

Available for the Content Editor (_editables.content), the Block editable region (_editables.block), and Rich Text inputs (_inputs.key_name.options).

left — String#

This key enables a tool to left align selected text by toggling a class name for that text block. The value is the class name to align the text. The styles for this class must be defined in the styles file.

Available for the Content Editor (_editables.content), the Block editable region (_editables.block), and Rich Text inputs (_inputs.key_name.options).

center — String#

This key enables a tool to center align selected text by toggling a class name for that text block. The value is the class name to align the text. The styles for this class must be defined in the styles file.

Available for the Content Editor (_editables.content), the Block editable region (_editables.block), and Rich Text inputs (_inputs.key_name.options).

right — String#

This key enables a tool to right align selected text by toggling a class name for that text block. The value is the class name to align the text. The styles for this class must be defined in the styles file.

Available for the Content Editor (_editables.content), the Block editable region (_editables.block), and Rich Text inputs (_inputs.key_name.options).

justify — String#

This key enables a tool to justify selected text by toggling a class name for that text block. The value is the class name to align the text. The styles for this class must be defined in the styles file.

Available for the Content Editor (_editables.content), the Block editable region (_editables.block), and Rich Text inputs (_inputs.key_name.options).

The styles CCS file must be in plain CSS.

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; }

If both source and output styles CSS files exist, CloudCannon will default to the source file.

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.

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 present but the preview will not show any styling.

List options#

The following options are available in the WYSIWYG toolbar for managing lists:

cloudcannon.config.yaml

copied

_editables:
  content:
    bulletedlist: true
    numberedlist: true
    indent: true
    outdent: true
    join_above: true
    join_below: true

cloudcannon.config.json

copied

{
  "_editables": {
    "content": {
      "bulletedlist": true,
      "numberedlist": true,
      "indent": true,
      "outdent": true,
      "join_above": true,
      "join_below": true
    }
  }
}

bulletedlist — Boolean#

This key enables a tool to insert an unordered list or convert selected text to an unordered list.

Available for the Content Editor (_editables.content), the Block editable region (_editables.block), and Rich Text inputs (_inputs.key_name.options).

numberedlist — Boolean#

This key enables a tool to insert an ordered list or convert selected text to an ordered list.

Available for the Content Editor (_editables.content), the Block editable region (_editables.block), and Rich Text inputs (_inputs.key_name.options).

indent — Boolean#

This key enables a tool to increase the indentation of a list item in an ordered or unordered list.

Available for the Content Editor (_editables.content), the Block editable region (_editables.block), and Rich Text inputs (_inputs.key_name.options).

outdent — Boolean#

This key enables a tool to decrease the indentation of a list item in an ordered or unordered list.

Available for the Content Editor (_editables.content), the Block editable region (_editables.block), and Rich Text inputs (_inputs.key_name.options).

join_above — Boolean#

This key enables a tool to merge a list item with the item above it in an ordered or unordered list.

Available for the Content Editor (_editables.content), the Block editable region (_editables.block), and Rich Text inputs (_inputs.key_name.options).

join_below — Boolean#

This key enables a tool to merge a list item with the item below it in an ordered or unordered list.

Available for the Content Editor (_editables.content), the Block editable region (_editables.block), and Rich Text inputs (_inputs.key_name.options).

Image options#

The following options are available in the WYSIWYG toolbar for image formatting:

cloudcannon.config.yaml

copied

_editables:
  content:
    image_size_attributes: true
    width: 800
    height: 400
    resize_style: contain
    mime_type: image/png
    expandable: true
    allowed_sources:
      - site-files
      - reference_key

cloudcannon.config.json

copied

{
  "_editables": {
    "content": {
      "image_size_attributes": true,
      "width": 800,
      "height": 400,
      "resize_style": "contain",
      "mime_type": "image/png",
      "expandable": true,
      "allowed_sources": [
        "site-files",
        "reference_key"
      ]
    }
  }
}

image_size_attributes — Boolean#

This key instructs a rich text editor to save width and height on image elements. 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 the Content Editor (_editables.content), the Block editable region (_editables.block), the Image editable region (_editables.image), and Rich Text inputs (_inputs.key_name.options).

width — Integer#

This key defines the width of the bounding box used in the resizing method defined by resize_style.

height — Integer#

This key defines the height of the bounding box used in the resizing method defined by resize_style.

resize_style — String#

This key defines how image files are resized prior to upload, using a bounding box defined by width and height options. Defaults to contain. Valid values are 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

This key does not apply to existing images, and does not work if width and height options are not defined.

mime_type — String#

This key defines what format an image is converted to prior to upload. Defaults to keeping the mime type of the uploaded file. Valid values are image/jpeg, image/png, or image/webp.

expandable — Boolean#

This key defines whether you can upscale an image to fit the bounding box while resizing an image prior to upload. Defaults to false. Has no effect if files are not resized.

allowed_sources — Array#

This key lists which DAMs you are allowed to upload to and browse. Valid values include site-files and the reference key for any DAM connected to your site.

If site-files is omitted from the array, site files will not be available as an asset source for this input.

Block options#

The following options are available in the WYSIWYG toolbar for adding media and full-width content elements:

cloudcannon.config.yaml

copied

_editables:
  content:
    code: true
    embed: true
    horizontalrule: true
    image: true
    table: true
    snippet: true

cloudcannon.config.json

copied

{
  "_editables": {
    "content": {
      "code": true,
      "embed": true,
      "horizontalrule": true,
      "image": true,
      "table": true,
      "snippet": true
    }
  }
}

code — Boolean#

This key enables two tools to turn selected text into inline code and selected text into a code block.

Available for the Content Editor (_editables.content), the Block editable region (_editables.block), and Rich Text inputs (_inputs.key_name.options).

embed — Boolean#

This key enables a tool to insert a region of raw HTML for Youtube, Vimeo, social media posts, or other media. Embedded content is sanitized to mitigate XSS risks, which includes removing style tags. Embeds containing script tags are not loaded a rich text editor.

Available for the Content Editor (_editables.content), the Block editable region (_editables.block), and Rich Text inputs (_inputs.key_name.options).

horizontalrule — Boolean#

This key enables a tool to insert a horizontal line.

Available for the Content Editor (_editables.content), the Block editable region (_editables.block), and Rich Text inputs (_inputs.key_name.options).

image — Boolean#

This key enables a tool to insert an image and enter alternative text and title text. Select an existing image, upload an image, or use an external link.

Available for the Content Editor (_editables.content), the Block editable region (_editables.block), and Rich Text inputs (_inputs.key_name.options).

table — Boolean#

This key enables a tool to insert a table. Further table options are available from the table context menu in the rich text editor.

Available for the Content Editor (_editables.content), the Block editable region (_editables.block), and Rich Text inputs (_inputs.key_name.options).

snippet — Boolean#

This key enables a tool to insert a Snippet, if any are available.

Available for the Content Editor (_editables.content), the Block editable region (_editables.block), and Rich Text inputs (_inputs.key_name.options).

Action options#

The following options are available in the WYSIWYG toolbar for user actions when editing and formatting content:

cloudcannon.config.yaml

copied

_editables:
  content:
    undo: true
    redo: true
    removeformat: true
    copyformatting: true

cloudcannon.config.json

copied

{
  "_editables": {
    "content": {
      "undo": true,
      "redo": true,
      "removeformat": true,
      "copyformatting": true
    }
  }
}

undo — Boolean#

This key enables a tool to undo recent edits. Undo is always enabled through standard OS-specific keyboard shortcuts.

Available for the Content Editor (_editables.content), the Block editable region (_editables.block), the Text editable region (_editables.text), and Rich Text inputs (_inputs.key_name.options).

redo — Boolean#

This key enables a tool to redo recent edits undone with undo. Undo is always enabled through standard OS-specific keyboard shortcuts.

removeformat — Boolean#

This key enables a tool to remove formatting from selected text. Applies to bold, italic, underline, strike, subscript, and superscript formatting. Does not remove other styles or formatting.

copyformatting — Boolean#

This key enables a tool to copy formatting from selected text. Applies to bold, italic, underline, strike, subscript, and superscript formatting. Does not copy other styles or formatting.

Paths#

The following options are available for determining where new asset files upload to, the file names for newly uploaded assets, and the default path for selecting existing assets:

cloudcannon.config.yaml

copied

_editables:
  content:
    paths:
      dam_static: 
      dam_uploads: 
      dam_uploads_filename: 
      static: 
      uploads: 
      uploads_filename:

cloudcannon.config.json

copied

{
  "_editables": {
    "content": {
      "paths": {
        "dam_static": null,
        "dam_uploads": null,
        "dam_uploads_filename": null,
        "static": null,
        "uploads": null,
        "uploads_filename": null
      }
    }
  }
}

paths — Object#

This key enables you to define paths for your Rich Text editors or File inputs. The following nested keys are available:

dam_static
dam_uploads
dam_uploads_filename
static
uploads
uploads_filename
uploads_use_relative_paths

This key has no default. If undefined at higher levels of the configuration cascade, paths will default to any values configured in the CloudCannon configuration file.

For more information, please read our documentation on Rich Text editors or File inputs.

Available for the Content Editor (_editables.content), the Block editable region (_editables.block), the Image editable region (_editables.image), the Text editable region (_editables.text), and Rich Text inputs (_inputs.key_name.options).

paths.dam_static — String#

This key enables you to define the path for the location of statically copied assets for DAM files.

paths.dam_uploads — String#

This key enables you to define the path for the default location of newly uploaded DAM files.

You can use dynamic placeholders for uploads and dam_uploads. For more information, please read our documentation on adjusting file upload paths.

paths.dam_uploads_filename — String#

This key enables you to define the path for the name of the uploaded file, when uploading DAM files.

paths.static — String#

This key enables you to define the path for the location of statically copied assets.

paths.uploads — String#

This key enables you to define the paths for the default location of newly uploaded site files.

You can use dynamic placeholders for uploads and dam_uploads. For more information, please read our documentation on adjusting file upload paths.

paths.uploads_filename — String#

This key enables you to define the path for the name of the uploaded file.

Custom markup#

The following options are available for handling HTML or Markdown structures that cannot be recreated in a rich text editor:

cloudcannon.config.yaml

copied

_editables:
  content:
    allow_custom_markup: false
    remove_custom_markup: false

cloudcannon.config.json

copied

{
  "_editables": {
    "content": {
      "allow_custom_markup": false,
      "remove_custom_markup": false
    }
  }
}

allow_custom_markup — Boolean#

This key 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 the Content Editor 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#

This key 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, the Content Editor, 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.

Rich text editor reference

WYSIWYG toolbar#

Text options#

Style and alignment options#

List options#

Image options#

Block options#

Action options#

Paths#

Custom markup#