☁️ Loving our new documentation website? Provide feedback in the CloudCannon Community! ✨

Developer ReferenceConfiguration File

options

Table of contents

Description:

This key defines configuration options for content parser configurations.

The value is an object that can contain editor_key, indented_by, default, trim_text, allow_nested, raw, forbidden_tokens, optional, allow_leading, escape_indented_blocks, parse_newline_character, ignore_unpaired_backticks, escape_fenced_blocks, and style properties. These options control how content between snippet boundaries is parsed.

Appears in:
└── Snippet
    └── params
        └── *
            └── Content Parser Configuration
                └── options
Type:
Object Required
Properties:
allow_leadingboolean#

This key toggles whether the first line of the content needs to be indented when an indented_by value is set.

Setting this key to true will allow the first line of the content to not be indented, but subsequent lines must be indented.

By default, this key is false (i.e., all lines including the first must be indented).

Show examplesHide examples
Copied to clipboard
parser: content
options:
  editor_key: highlighted_text
  indented_by: '  '
  allow_leading: true
{
  "parser": "content",
  "options": {
    "editor_key": "highlighted_text",
    "indented_by": "  ",
    "allow_leading": true
  }
}

Example usage:

Markdown
Copied to clipboard
## My blog post

<<highlight>>
  My highlighted content!   
<</highlight>>

<<highlight>>Some initial content
    More highlighted content!   
<</highlight>>

Morbi leo risus, porta ac consectetur ac, vestibulum at eros.
/page.md

This will parse correctly as My highlighted content!

This will also parse correctly, as Some initial content\nMore highlighted content!, despite the first line not being indented.

allow_nestedboolean#

This key toggles whether nested snippets will be parsed and returned.

Setting this key to true will parse and return nested snippets.

By default, this key is false (i.e., nested snippets are not parsed and returned).

Show examplesHide examples
Copied to clipboard
parser: content
options:
  editor_key: highlighted_text
  allow_nested: true
{
  "parser": "content",
  "options": {
    "editor_key": "highlighted_text",
    "allow_nested": true
  }
}

Example usage:

Markdown
Copied to clipboard
## My blog post

<<highlight>>
  My highlighted <<highlight>>content!<</highlight>>   
<</highlight>>

Morbi leo risus, porta ac consectetur ac, vestibulum at eros.
/page.md

With allow_nested turned on, the content parser will detect and parse the nested <<highlight>> tags as another snippet, rather than plaintext.

This doesn't have to be the same snippet, any configured snippet will be parsed inside the content parser.

If allow_nested is set to false, inner snippets will still be parsed, but will not be returned. This means that in the above example, My highlighted <<highlight>>content!<</highlight>> would be the raw text with allow_nested: false. If inner snippets were not parsed, the content parser would end parsing at the first <</highlight>>, giving you the text: My highlighted <<highlight>>content!. This is the behavior of the raw option.

defaultstring#

This key defines the default number of literals, which is used when adding a new snippet to a page in CloudCannon.

editor_keystring#

This key defines the key that a user in CloudCannon will see to edit this value.

The value returned by this parser is a number input that can be edited to change how many literals are output by the parser.

Show examplesHide examples
Copied to clipboard
_snippets:
  custom_title:
    snippet: '[[hashes]] [[title]]'
    params:
      hashes:
        parser: repeating_literal
        options:
          literal: '#'
          minimum: 1
          editor_key: heading_level
      title:
        parser: content
        options:
          editor_key: title
          forbidden_tokens:
            - |+
{
  "_snippets": {
    "custom_title": {
      "snippet": "[[hashes]] [[title]]",
      "params": {
        "hashes": {
          "parser": "repeating_literal",
          "options": {
            "literal": "#",
            "minimum": 1,
            "editor_key": "heading_level"
          }
        },
        "title": {
          "parser": "content",
          "options": {
            "editor_key": "title",
            "forbidden_tokens": [
              "\n"
            ]
          }
        }
      }
    }
  }
}

Example usage:

Markdown
Copied to clipboard
# My blog post 

Aenean lacinia bibendum nulla sed consectetur.

## My heading 

Morbi leo risus, porta ac consectetur ac, vestibulum at eros.
/page.md

If editing these as snippets in CloudCannon, the editor will see heading_level as a number input. Changing this value will add or remove # characters to the source code to match the number.

escape_fenced_blocksboolean#

This key toggles whether CloudCannon will escape fenced code blocks (triple backticks) when parsing content.

Setting this key to true will escape fenced code blocks in the content, preventing them from being interpreted as code blocks.

By default, this key is false (i.e., fenced code blocks are not escaped).

Defaults to: false

Show examplesHide examples

In this example, we have configured content parser to escape fenced code blocks.

Copied to clipboard
_snippets:
  highlight:
    snippet: <<highlight>> [[content]] <</highlight>>
    params:
      content:
        parser: content
        options:
          editor_key: highlighted_text
          escape_fenced_blocks: true
{
  "_snippets": {
    "highlight": {
      "snippet": "<<highlight>> [[content]] <</highlight>>",
      "params": {
        "content": {
          "parser": "content",
          "options": {
            "editor_key": "highlighted_text",
            "escape_fenced_blocks": true
          }
        }
      }
    }
  }
}
escape_indented_blocksboolean#

This key toggles whether CloudCannon will escape indented code blocks (4 spaces) when parsing content.

Setting this key to true will escape indented code blocks in the content, preventing them from being interpreted as code blocks.

By default, this key is false (i.e., indented code blocks are not escaped).

Defaults to: false

Show examplesHide examples

In this example, we have configured content parser to escape indented code blocks.

Copied to clipboard
_snippets:
  highlight:
    snippet: <<highlight>> [[content]] <</highlight>>
    params:
      content:
        parser: content
        options:
          editor_key: highlighted_text
          escape_indented_blocks: true
{
  "_snippets": {
    "highlight": {
      "snippet": "<<highlight>> [[content]] <</highlight>>",
      "params": {
        "content": {
          "parser": "content",
          "options": {
            "editor_key": "highlighted_text",
            "escape_indented_blocks": true
          }
        }
      }
    }
  }
}
forbidden_tokensArray<forbidden_tokens[*]>#

This key defines tokens that stop parsing content when encountered in content parser configurations.

The value is an array of strings, where each string specifies a forbidden token. This is useful when the content parser is being greedy and consuming more input than intended.

Show examplesHide examples

In this example, we have configured forbidden tokens to stop parsing when encountering a less-than sign.

Copied to clipboard
_snippets:
  highlight:
    snippet: <<highlight>> [[content]] <</highlight>>
    params:
      content:
        parser: content
        options:
          editor_key: highlighted_text
          forbidden_tokens:
            - <
{
  "_snippets": {
    "highlight": {
      "snippet": "<<highlight>> [[content]] <</highlight>>",
      "params": {
        "content": {
          "parser": "content",
          "options": {
            "editor_key": "highlighted_text",
            "forbidden_tokens": [
              "<"
            ]
          }
        }
      }
    }
  }
}
ignore_unpaired_backticksboolean#

This key toggles whether CloudCannon will ignore unpaired backticks when parsing content.

Setting this key to false will cause CloudCannon to treat unpaired backticks as parsing errors.

By default, this key is true (i.e., unpaired backticks are ignored).

Defaults to: true

Show examplesHide examples

In this example, we have configured content parser to ignore unpaired backticks.

Copied to clipboard
_snippets:
  highlight:
    snippet: <<highlight>> [[content]] <</highlight>>
    params:
      content:
        parser: content
        options:
          editor_key: highlighted_text
          ignore_unpaired_backticks: true
{
  "_snippets": {
    "highlight": {
      "snippet": "<<highlight>> [[content]] <</highlight>>",
      "params": {
        "content": {
          "parser": "content",
          "options": {
            "editor_key": "highlighted_text",
            "ignore_unpaired_backticks": true
          }
        }
      }
    }
  }
}
indented_bystring#

This key defines the whitespace indentation required when parsing content.

Configures the content parser to require whitespace indentation when parsing. Used when a snippet continues for as long as content is indented.

This option should only be used if required, since it prevents your Snippet from parsing if the whitespace does not match.

If you want parsing to be flexible, but the output to be formatted, use the Style options instead.

Show examplesHide examples
Copied to clipboard
_snippets:
  highlight:
    snippet: |-
      <<highlight>>
      [[inner]]
      <</highlight>>
    params:
      inner:
        parser: content
        options:
          editor_key: highlighted_text
          indented_by: '  '
{
  "_snippets": {
    "highlight": {
      "snippet": "<<highlight>>\n[[inner]]\n<</highlight>>",
      "params": {
        "inner": {
          "parser": "content",
          "options": {
            "editor_key": "highlighted_text",
            "indented_by": "  "
          }
        }
      }
    }
  }
}

Example usage:

Markdown
Copied to clipboard
## My blog post

<<highlight>>
  My highlighted content!   
<</highlight>>

<<highlight>>
    My highlighted content! 
<</highlight>>

<<highlight>>
My highlighted content!     
<</highlight>>

Morbi leo risus, porta ac consectetur ac, vestibulum at eros.
/page.md

This will parse correctly as My highlighted content!

This will strip only the indentation that matches, and return My highlighted content!

This will not match this parser, as indentation is required. Use the style.block.indent option instead.

optionalboolean#

This key toggles whether CloudCannon will treat content as optional when parsing snippet parameters.

Setting this key to true will make the content parameter optional, allowing snippets to match even when the content is missing.

By default, this key is false (i.e., content is required).

Show examplesHide examples

In this example, we have configured content parser to treat content as optional.

Copied to clipboard
_snippets:
  highlight:
    snippet: <<highlight>> [[content]] <</highlight>>
    params:
      content:
        parser: content
        options:
          editor_key: highlighted_text
          optional: true
{
  "_snippets": {
    "highlight": {
      "snippet": "<<highlight>> [[content]] <</highlight>>",
      "params": {
        "content": {
          "parser": "content",
          "options": {
            "editor_key": "highlighted_text",
            "optional": true
          }
        }
      }
    }
  }
}
parse_newline_characterboolean#

This key toggles whether the parser treats \n as line breaks instead of literal characters.

Setting this key to true will treat \n as line breaks instead of literal characters. This is useful if you are editing your content in a multiline editing interface.

By default, this key is false (i.e., \n is treated as literal characters).

Defaults to: false

Show examplesHide examples
Copied to clipboard
parser: content
options:
  parse_newline_character: true
{
  "parser": "content",
  "options": {
    "parse_newline_character": true
  }
}

Example usage:

Markdown
Copied to clipboard
## My blog post

<<highlight>> Line One\nLine Two <</highlight>>
/page.md

This content will be displayed on two lines when opened in an editing interface, instead of showing the literal \n characters.

rawboolean#

This key toggles whether the parser performs no parsing of the inner text.

Setting this key to true will perform no parsing of the inner text. This is a stricter version of allow_nested: false. Useful to improve the performance of the content parser, but can misbehave.

By default, this key is false (i.e., inner text is parsed).

Show examplesHide examples
Copied to clipboard
parser: content
options:
  editor_key: highlighted_text
  raw: true
{
  "parser": "content",
  "options": {
    "editor_key": "highlighted_text",
    "raw": true
  }
}

Example usage:

Markdown
Copied to clipboard
## My blog post

<<highlight>>
  My highlighted <<highlight>>content!<</highlight>>   
<</highlight>>

Morbi leo risus, porta ac consectetur ac, vestibulum at eros.
/page.md

With raw turned on, the content parser will perform no parsing on the text it is capturing. This means that the nested <<highlight>> will not be detected as a snippet and the first <</highlight>> tag found will end the content parser, giving you the parsed content My highlighted <<highlight>>content!.

styleObject#

This key defines styling options for snippet output formatting.

The value is an object that can contain output, inline, and block properties. These options control how snippet content is parsed and formatted to produce cleaner source code.

Show examplesHide examples

In this example, we have configured snippet style with inline and block formatting options.

Copied to clipboard
_snippets:
  highlight:
    snippet: <<highlight>> [[content]] <</highlight>>
    params:
      content:
        parser: content
        options:
          style:
            inline:
              leading: ' '
              trailing: ' '
            block:
              leading: \n
              trailing: \n
              indent: '  '
{
  "_snippets": {
    "highlight": {
      "snippet": "<<highlight>> [[content]] <</highlight>>",
      "params": {
        "content": {
          "parser": "content",
          "options": {
            "style": {
              "inline": {
                "leading": " ",
                "trailing": " "
              },
              "block": {
                "leading": "\\n",
                "trailing": "\\n",
                "indent": "  "
              }
            }
          }
        }
      }
    }
  }
}
trim_textboolean#

This key toggles whether all whitespace and newlines will be trimmed from the start and end of the content before it is presented to an editor in CloudCannon.

Setting this key to true will trim all whitespace and newlines from the start and end of the content.

By default, this key is false (i.e., whitespace and newlines are not trimmed).

Show examplesHide examples
Copied to clipboard
parser: content
options:
  editor_key: highlighted_text
  trim_text: true
{
  "parser": "content",
  "options": {
    "editor_key": "highlighted_text",
    "trim_text": true
  }
}

Example usage:

Markdown
Copied to clipboard
## My blog post

<<highlight>>
  My highlighted content!   
<</highlight>>

<<highlight>>  My highlighted content!  <</highlight>> 

Morbi leo risus, porta ac consectetur ac, vestibulum at eros.
/page.md

Both of these will parse as My highlighted content!, despite the newlines and whitespace surrounding them.

To add whitespace back in when outputting the snippet, use the Style options.

Examples:

In this example, we have configured content parser options with an editor key and forbidden tokens.

Copied to clipboard
_snippets:
  highlight:
    snippet: <<highlight>> [[content]] <</highlight>>
    params:
      content:
        parser: content
        options:
          editor_key: highlighted_text
          forbidden_tokens:
            - <
{
  "_snippets": {
    "highlight": {
      "snippet": "<<highlight>> [[content]] <</highlight>>",
      "params": {
        "content": {
          "parser": "content",
          "options": {
            "editor_key": "highlighted_text",
            "forbidden_tokens": [
              "<"
            ]
          }
        }
      }
    }
  }
}
Open in a new tab