Configure a Code 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 Code input is an editing interface for code or mono-spaced plain text content. By configuring your inputs, you can customize the appearance and functionality for a better editing experience.

A screenshot of the Code Input in the Data Editor shows code in a text area with syntax highlighting.

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

To configure a Code 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, the frontmatter of 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 code.
(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., syntax, theme, show_gutter).

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.

Copied to clipboard

_inputs:
  example_ruby:
    type: code

{
  "_inputs": {
    "example_ruby": {
      "type": "code"
    }
  }
}

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

This Code input is called example_ruby.

The value of the type key determines the input type. This is a code input.

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

YAML

Copied to clipboard

example_ruby: |
  def say_hello
    puts 'Hi there!'
  end

  say_hello

Input configuration options#

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

Specific configuration options for Code inputs include defining the height of the code area, tab size, theme color, gutter visibility, syntax highlighting, 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 Code input using some of the most commonly used configuration keys.

Copied to clipboard

_inputs:
  example_ruby:
    type: code
    label: Example Ruby Code
    comment: Enter the example code for the feature
    options:
      max_visible_lines: 25
      min_visible_lines: 15
      show_gutter: false
      syntax: ruby
      theme: darcula
      required: true

{
  "_inputs": {
    "example_ruby": {
      "type": "code",
      "label": "Example Ruby Code",
      "comment": "Enter the example code for the feature",
      "options": {
        "max_visible_lines": 25,
        "min_visible_lines": 15,
        "show_gutter": false,
        "syntax": "ruby",
        "theme": "darcula",
        "required": true
      }
    }
  }
}

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

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

options.empty_typestring#

This key defines how an 'empty' value will be saved. Does not apply to existing empty values.

Defaults to: null

Allowed values: null string

Appears in: Text Input options, Textarea Input options, Code Input options, Color Input options, URL Input options, Select Input options, Rich Text Input options, Date/Datetime Input options, Time Input options, File Input options, Choice Input options.

options.max_lengthnumber#

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 examplesHide examples

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.

Copied to clipboard

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

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

options.max_length_messagestring#

This key defines a custom error message that explains why a value has failed the validation criteria from options.max_length.

This key requires you to define options.max_length.

This key has no default.

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

Show examplesHide examples

In this example, we prompt our team to enter a valid number of characters using a custom message.

Copied to clipboard

_inputs:
  seo_description:
    type: markdown
    comment: Enter a brief description of this blog.
    options:
      max_length: 125
      max_length_message: You are only allowed 125 characters.
      min_length: 25
      min_length_message: Please write more than 25 characters.

{
  "_inputs": {
    "seo_description": {
      "type": "markdown",
      "comment": "Enter a brief description of this blog.",
      "options": {
        "max_length": 125,
        "max_length_message": "You are only allowed 125 characters.",
        "min_length": 25,
        "min_length_message": "Please write more than 25 characters."
      }
    }
  }
}

options.max_visible_linesnumber#

This key defines the maximum number of visible lines for this input, effectively controlling maximum height.

When the containing text exceeds this number, the input becomes a scroll area.

Appears in: Code Input options.

options.min_lengthnumber#

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 examplesHide examples

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.

Copied to clipboard

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

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

options.min_length_messagestring#

This key defines a custom error message that explains why a value has failed the validation criteria from options.min_length.

This key requires you to define options.min_length.

This key has no default.

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

Show examplesHide examples

In this example, we prompt our team to enter a valid number of characters using a custom message.

Copied to clipboard

_inputs:
  seo_description:
    type: markdown
    comment: Enter a brief description of this blog.
    options:
      max_length: 125
      max_length_message: You are only allowed 125 characters.
      min_length: 25
      min_length_message: Please write more than 25 characters.

{
  "_inputs": {
    "seo_description": {
      "type": "markdown",
      "comment": "Enter a brief description of this blog.",
      "options": {
        "max_length": 125,
        "max_length_message": "You are only allowed 125 characters.",
        "min_length": 25,
        "min_length_message": "Please write more than 25 characters."
      }
    }
  }
}

options.min_visible_linesnumber#

This key defines the minimum number of visible lines for this input, effectively controlling initial height.

When the containing text exceeds this number, the input grows line by line to the lines defined by max_visible_lines.

Appears in: Code Input options.

options.patternstring#

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.

If your REGEX string includes a \ character and CloudCannon Configuration File is a .yml file, use single quotes ' around the string to avoid a build error.

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 examplesHide examples

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

Copied to clipboard

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

options.pattern_flagsObject#

This key defines the flags (e.g. case-insensitive searching) for the regular expression set in options.pattern.

Show examplesHide examples

In this example, we have configured pattern flags for a text input to enable case-insensitive searching.

Copied to clipboard

_inputs:
  search_term:
    type: text
    options:
      pattern: ^[a-z]+$
      pattern_flags:
        ignore_case: true

{
  "_inputs": {
    "search_term": {
      "type": "text",
      "options": {
        "pattern": "^[a-z]+$",
        "pattern_flags": {
          "ignore_case": true
        }
      }
    }
  }
}

options.pattern_flags.dot_allboolean#

This key defines the s flag - . matches newline characters.

Defaults to: false

Appears in: pattern_flags.

options.pattern_flags.globalboolean#

This key defines the g flag - Search globally.

Defaults to: false

Appears in: pattern_flags.

options.pattern_flags.ignore_caseboolean#

This key defines the i flag - Case-insensitive.

Defaults to: false

Appears in: pattern_flags.

options.pattern_flags.multilineboolean#

This key defines the m flag - ^ and $ match the start and end of each line rather than the entire string.

Defaults to: false

Appears in: pattern_flags.

options.pattern_flags.unicodeboolean#

This key defines the u flag - Pattern is treated as a sequence of Unicode code points.

Defaults to: false

Appears in: pattern_flags.

options.pattern_flags.unicode_setsboolean#

This key defines the v flag for extended unicode mode.

Defaults to: false

Appears in: pattern_flags.

options.pattern_messagestring#

This key defines a custom error message that explains why a value has failed the validation criteria from options.pattern.

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 examplesHide examples

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

Copied to clipboard

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

options.requiredboolean#

This key toggles whether CloudCannon requires this Input to have a value.

Setting this key to true 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, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.

Defaults to: false

Appears in: Text Input options, Textarea Input options, Code Input options, Color Input options, Number Input options, Range Input options, URL Input options, Select Input options, Rich Text Input options, Date/Datetime Input options, Time Input options, File Input options, Multiselect Input options, Choice Input options, Multichoice Input options, Object Input options, Array Input options.

Show examplesHide examples

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

Copied to clipboard

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

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

options.required_messagestring#

This key defines a custom error message that explains why a value has failed the validation criteria from options.required.

This key requires you to define options.required.

This key has no default.

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

Show examplesHide examples

In this example, we prompt our team to enter an Input value using a required message.

Copied to clipboard

_inputs:
  author:
    type: text
    comment: Enter the name of the author for this blog post.
    options:
      required: true
      required_message: You are not allowed to leave this blank.

{
  "_inputs": {
    "author": {
      "type": "text",
      "comment": "Enter the name of the author for this blog post.",
      "options": {
        "required": true,
        "required_message": "You are not allowed to leave this blank."
      }
    }
  }
}

options.show_gutterboolean#

This key toggles whether CloudCannon displays line numbers in the gutter of Code Inputs.

Setting this key to false will hide line numbers in the left gutter of the code editor.

By default, this key is true (i.e., line numbers are displayed).

Defaults to: true

Appears in: Code Input options.

Show examplesHide examples

In this example, we have configured a code input to hide line numbers by setting show_gutter to false.

Copied to clipboard

_inputs:
  css_code:
    type: code
    label: Custom CSS
    options:
      show_gutter: false

{
  "_inputs": {
    "css_code": {
      "type": "code",
      "label": "Custom CSS",
      "options": {
        "show_gutter": false
      }
    }
  }
}

options.soft_wrapboolean#

This key toggles whether long lines wrap to the next line in Code Inputs.

Setting this key to true will wrap lines that exceed the width of the code area to the next line without adding a line break character.

By default, this key is false (i.e., long lines extend horizontally and require horizontal scrolling).

Defaults to: false

Appears in: Code Input options.

Show examplesHide examples

In this example, we have configured a code input to enable soft line wrapping for better readability of long lines.

Copied to clipboard

_inputs:
  markdown_content:
    type: code
    label: Markdown
    options:
      soft_wrap: true

{
  "_inputs": {
    "markdown_content": {
      "type": "code",
      "label": "Markdown",
      "options": {
        "soft_wrap": true
      }
    }
  }
}

options.syntaxstring#

This key defines how the editor parses your content for syntax highlighting.

Should be set to the language of the code going into the input.

You can also configure this key using the naming convention: syntax is assumed to be the section preceding the normalized _code_block suffix (e.g. my_javascript_code_block resolves to javascript).

Allowed values: c_cpp clojure cobol coffee csharp css d dart diff dockerfile and 58 more.

Appears in: Code Input options.

options.tab_sizenumber#

This key defines the number of spaces inserted when the Tab key is pressed in a Code Input.

The value is a number representing the number of spaces. This affects both indentation behavior and how existing tabs are displayed.

Defaults to: 2

Appears in: Code Input options.

Show examplesHide examples

In this example, we have configured a code input to use 4 spaces for indentation instead of the default 2.

Copied to clipboard

_inputs:
  python_code:
    type: code
    label: Python Code
    options:
      tab_size: 4

{
  "_inputs": {
    "python_code": {
      "type": "code",
      "label": "Python Code",
      "options": {
        "tab_size": 4
      }
    }
  }
}

options.themestring#

This key defines the color theme used for syntax highlighting in Code Inputs.

By default, this key is basic_dark.

Defaults to: basic_dark

Allowed values: atomone basic_dark basic_light darcula dracula duotone_dark duotone_light eclipse github_dark github_light and 15 more.

Appears in: Code Input options.

Show examplesHide examples

In this example, we have configured a code input to use the dracula theme for a dark-colored editing experience.

Copied to clipboard

_inputs:
  javascript_code:
    type: code
    label: JavaScript
    options:
      theme: dracula

{
  "_inputs": {
    "javascript_code": {
      "type": "code",
      "label": "JavaScript",
      "options": {
        "theme": "dracula"
      }
    }
  }
}

Valid values#

Code inputs can have multiple valid values for empty, single-line, and multiline content. Here are some examples of valid values for the key code.

Empty/null value:

code:

Any valid string (quoted or unquoted):

code: ""
code: ''
code: any string
code: "any string"
code: 'any string'

Any valid multiline string:

code: > multiline string
code: >- multiline string
code: >+ multiline string
code: | multiline string
code: |- multiline string
code: |+ multiline string

Any valid string:

code = ""
code = "any string"

Any valid escaped string:

code = ''
code = 'any string (literal)'

Any valid multiline string:

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

Null value:

"code": null

Any valid string:

"code": ""
"code": "any string"

Any valid multiline string:

"code": "multiline \n string"

Unconfigured Code inputs#

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

CloudCannon will interpret any unconfigured input with the key name code_block, or that ends in _code_block as a Code input.

Markdown

Copied to clipboard

---
code_block: |
  Some content is better in monospace.

  1 + 1 = 2
  2 + 2 = 4
---

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.

User Articles

User Guides

User Glossary

Developer Articles

Developer Guides

Developer Reference

Configure a Code input

On this page

Input configuration options#

Valid values#

Unconfigured Code inputs#

Related Resources

Configure a Code input

On this page

Input configuration options#

Valid values#

Unconfigured Code inputs#

Related Resources

What are inputs?

What is a Code input?

What is the Data Editor?