Configure a Rich Text input

Permissions required

Members of all Default Permission Groups, or Custom Permission Groups with the site:file:write permission, can configure inputs in all locations in the configuration cascade. You can limit permission to specific locations in the configuration using file globs.

A Rich Text input is an editing interface for markup content. By configuring your inputs, you can customize the appearance and functionality for a better editing experience.

A screenshot of an HTML Rich Text input in the Data Editor.

You can configure the WYSIWYG toolbar for a Rich Text input in the same way you configure the toolbar for the Content Editor. For more information, please read our documentation on configuring your Rich Text editors.

These instructions assume that you know where in the configuration cascade you want to configure your input. For more information, please read our documentation on Rick Text inputs, inputs in general, and the configuration cascade.

To configure a Rich Text input:

Open your website files in your local development environment, or log in to CloudCannon and select the Site for which you want to configure your input.
Navigate to the location in the configuration cascade where you want to configure your input. This can be the root of your CloudCannon Configuration File, within the collections_config.* key in your CloudCannon Configuration File, a Schema file, a markup file, or any where you configure a Structure.
Identify the _inputs key, or create one at that level of the configuration cascade.
Add an input name key for your input under the _inputs key (a.k.a., _inputs.*). We recommend naming your input something simple that indicates the function or context.
Add the type key under your input name key, with the value html or markdown.
(Optional.) Add any other general configuration keys (e.g., label, comment, context) under your input name key.
(Optional.) Add any specific configuration keys under _inputs.*.options (e.g., allow_resize, initial_height, paths).

CloudCannon will now apply this input configuration to all markup files that use your input name key, without needing to save your configuration. This allows you to make changes to your input configuration and see those changes affect inputs live.

When you are happy with your input configuration, you must save your input configuration.

cloudcannon.config.yaml

copied

_inputs:
  content:
    type: html
  top_copy:
    type: markdown

All inputs are defined under the _inputs key, regardless of where they are in the configuration cascade.

The Rich Text input is called content.

The value of the type key determines the input type. This is an html Rich Text input.

The Rich Text input is called top_copy.

The value of the type key determines the input type. This is a markdown Rich Text input.

cloudcannon.config.json

copied

{
  "_inputs": {
    "content": {
      "type": "html"
    },
    "top_copy": {
      "type": "markdown"
    }
  }
}

All inputs are defined under the _inputs key, regardless of where they are in the configuration cascade.

The Rich Text input is called content.

The value of the type key determines the input type. This is an html Rich Text input.

The Rich Text input is called top_copy.

The value of the type key determines the input type. This is a markdown Rich Text input.

When you add your input key name to a data or markup file, your configured Rich Text input will appear in the Data Editor, Visual Editor, or Content Editor.

about.md

copied


---
content: |
  <p>This paragraph has <em>emphasis</em> and <strong>strength</strong>.</p>
  <ol>
    <li>Walk</li>
    <li>Run</li>
  </ol>
  <p>Linking to <a href="/">index</a>.</p>
top_copy: |
  # Animals

  - Dogs
  - Cats

  ***Its raining cats and dogs.***
---

You may need to convert the Markdown value into HTML to use it on your site, for example by using the markdownify filter in Jekyll or Hugo. For more information, please read our documentation on configuring your markdown engine.

Input configuration options#

General configuration options are available for all input types. You can define the label, comment, and context box for your Rich Text input, whether it is hidden or disabled, and how CloudCannon should handle configuration at multiple levels of the configuration cascade.

Specific configuration options for Rich Text inputs include configuring whether your team members are allowed to resize the text area, the initial height of the text area, the upload paths or filenames for any assets uploaded through this input, and how CloudCannon handles empty values. You can also add input validation to require a value, specify the minimum and maximum value length, or match a regular expression.

Here is an example of a Rich Text input using some of the most commonly used configuration keys.

cloudcannon.config.yaml

copied

_inputs:
  description:
    type: markdown
    label: Page Description
    comment: Enter the description for this page
    options:
      allow_resize: false
      initial_height: 200
      paths:
        dam_uploads: assets/images
        dam_uploads_filename: '[filename].[extension]'
      required: true
      max_length: 500

cloudcannon.config.json

copied

{
  "_inputs": {
    "description": {
      "type": "markdown",
      "label": "Page Description",
      "comment": "Enter the description for this page",
      "options": {
        "allow_resize": false,
        "initial_height": 200,
        "paths": {
          "dam_uploads": "assets/images",
          "dam_uploads_filename": "[filename].[extension]"
        },
        "required": true,
        "max_length": 500
      }
    }
  }
}

For a complete list of configuration keys available for inputs please read our inputs reference documentation.

These keys configure the appearance and functionality of Rich Text inputs in CloudCannon.

allow_resize — Boolean#

This key toggles the resize handler to vertically resize the text area of the input. Defaults to true.

initial_height — Integer#

This key defines the initial height of the input text area in pixels (px). Defaults to 320. Supports values between 135 and 1200.

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.

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 name of a file, after uploading it to a DAM.

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 path for the default location of newly uploaded 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 name of a file, after uploading it.

paths.uploads_use_relative_paths — Boolean#

This key enables you to use a file path relative to the current file when uploading through this input. File inputs in data files or front matter will also use relative file paths when selecting an existing file.

empty_type — string#

This key determines how CloudCannon handles an empty value. This key does not apply to existing empty values.

Value must be one of the following:

string - an empty value for this input will be stored as "".
null - an empty value for this input will be stored as a null value (default). This does not apply to TOML files.

_inputs.*.options.required — Boolean#

This key toggles whether CloudCannon requires this Input to have a value. If set to true, CloudCannon will require you to enter a value to save your changes, or discard your unsaved changes.

By default, this key is false (i.e, CloudCannon does not require this Input to have a value).

This key is available for Array, Boolean, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.

Show exampleHide example

In this example, we want to require our team to enter an author value for markup files with this Input.

cloudcannon.config.yaml

copied

_inputs:
  author:
    type: text
    comment: Enter the name of the author for this blog post.
    options:
      required: true

cloudcannon.config.json

copied

{
  "_inputs": {
    "author": {
      "type": "text",
      "comment": "Enter the name of the author for this blog post.",
      "options": {
        "required": true
      }
    }
  }
}

_inputs.*.options.max_length — Number#

This key defines the maximum string length, in characters, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too long. If the Input already contains a longer value, CloudCannon will require you to remove characters until the Input contains a valid string to save your changes, or discard your unsaved changes.

Value can be any non-negative integer. If this key is set to 0, CloudCannon requires the Input to be empty. If options.min_length is also configured, this key cannot be a smaller number.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs. To use this key in a Select Input, allow_create must be set to true.

Show exampleHide example

In this example, we want our team to enter a blog description using the Rich Text seo_description Input. This Input limits you to a maximum of 125 characters.

cloudcannon.config.yaml

copied

_inputs:
  seo_description:
    type: markdown
    comment: Enter a brief description of this blog.
    options:
      max_length: 125
      min_length: 25

cloudcannon.config.json

copied

{
  "_inputs": {
    "seo_description": {
      "type": "markdown",
      "comment": "Enter a brief description of this blog.",
      "options": {
        "max_length": 125,
        "min_length": 25
      }
    }
  }
}

_inputs.*.options.min_length — Number#

This key defines the minimum string length, in characters, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too short. If the Input already contains a shorter value, CloudCannon will require you to add characters until the Input contains a valid string to save your changes, or discard your unsaved changes.

Value can be any positive integer. If options.max_length is also configured, this key cannot be a greater number.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs. To use this key in a Select Input, allow_create must be set to true.

Show exampleHide example

In this example, we want our team to enter a blog description using the Rich Text seo_description Input. This Input requires a minimum of 25 characters.

cloudcannon.config.yaml

copied

_inputs:
  seo_description:
    type: markdown
    comment: Enter a brief description of this blog.
    options:
      max_length: 125
      min_length: 25

cloudcannon.config.json

copied

{
  "_inputs": {
    "seo_description": {
      "type": "markdown",
      "comment": "Enter a brief description of this blog.",
      "options": {
        "max_length": 125,
        "min_length": 25
      }
    }
  }
}

_inputs.*.options.pattern — String#

This key defines a regular expression that the Input value must match. When configured, CloudCannon will require you to enter a value that matches the REGEX pattern. If the Input already contains an invalid value, CloudCannon will require you to enter a valid string to save your changes, or discard your unsaved changes.

Value must be a valid REGEX string.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs. To use this key in a Select Input, allow_create must be set to true.

Show exampleHide example

In this example, we want our team to add an email address to the contact_email Input using the correct email format.

cloudcannon.config.yaml

copied

_inputs:
  contact_email:
    type: email
    options:
      pattern: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
      pattern_message: Please use the format ___@___.__

cloudcannon.config.json

copied

{
  "_inputs": {
    "contact_email": {
      "type": "email",
      "options": {
        "pattern": "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}",
        "pattern_message": "Please use the format ___@___.__"
      }
    }
  }
}

_inputs.*.options.pattern_message — String#

This key defines the message that explains which regular expression an Input will accept. This key requires you to define options.pattern.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.

Show exampleHide example

In this example, we prompt our team to use the correct email format in the contact_email Input using a pattern message.

cloudcannon.config.yaml

copied

_inputs:
  contact_email:
    type: email
    options:
      pattern: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
      pattern_message: Please use the format ___@___.__

cloudcannon.config.json

copied

{
  "_inputs": {
    "contact_email": {
      "type": "email",
      "options": {
        "pattern": "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}",
        "pattern_message": "Please use the format ___@___.__"
      }
    }
  }
}

Valid values#

Rich Text inputs can have multiple valid values for empty, single line, and multiline content. Here are some examples of valid values for the key html. These work for both HTML and Markdown inputs.

Empty/null value:

html:

Any valid string (quoted or unquoted):

html: ""
html: ''
html: any string
html: "any string"
html: 'any string'

Any valid multiline string:

html: > multiline string
html: >- multiline string
html: >+ multiline string
html: | multiline string
html: |- multiline string
html: |+ multiline string

Any valid string:

html = ""
html = "any string"

Any valid escaped string:

html = ''
html = 'any string (literal)'

Any valid multiline string:

html = """ multiline string"""
html = """\ multiline string (trimmed) \ """
html = ''' literal multiline string'''

Null value:

"html": null

Any valid string:

"html": ""
"html": "any string"

Any valid multiline string:

"html": "multiline \n string"

Unconfigured Rich Text inputs#

In some cases, CloudCannon can still detect a Rich Text input even if you have not configured it.

CloudCannon will interpret any unconfigured input with the key name html or markdown, or that ends in _html or _markdown, as a Rich Text input.

about.md

copied


---
sidebar_html: |
  <p>This paragraph has <em>emphasis</em> and <strong>strength</strong>.</p>
  <ol>
    <li>Walk</li>
    <li>Run</li>
  </ol>
  <p>Linking to <a href="/">index</a>.</p>
---

This behavior is convenient if you have simple inputs or do not want to configure inputs. It is also beneficial for new websites on CloudCannon where you have yet to create any CloudCannon-specific configuration.

We recommend configuring your inputs for greater control over their functionality and appearance.