Snippet Format

Description:

This key defines formatting options for parsing snippet parameters.

The value is an object that can contain various options controlling how snippet parameters are parsed, including boundaries, delimiters, allowed value types, and string formatting options.

Appears in:

├── Snippet
│   └── params
│       └── *
│           ├── Argument List Parser Configuration
│           │   └── options
│           │       └── Snippet Format
│           ├── Argument Parser Configuration
│           │   └── options
│           │       └── Snippet Format
│           └── Key Value List Parser Configuration
│               └── options
│                   └── Snippet Format
└── Snippet Definition Value
    └── Snippet Format

Type:

Object

Properties:

allow_booleansboolean#

This key toggles whether CloudCannon will allow unquoted boolean values like true and false when parsing snippet parameters.

Setting this key to true will allow unquoted boolean values in snippet parameter parsing.

By default, this key is false (i.e., unquoted boolean values are not allowed).

Show examplesHide examples

In this example, we have configured snippet format to allow unquoted boolean values.

Copied to clipboard

_snippets:
  example:
    snippet: <<example [[param]]>>
    params:
      param:
        parser: argument
        options:
          format:
            allow_booleans: true

{
  "_snippets": {
    "example": {
      "snippet": "<<example [[param]]>>",
      "params": {
        "param": {
          "parser": "argument",
          "options": {
            "format": {
              "allow_booleans": true
            }
          }
        }
      }
    }
  }
}

allow_implied_valuesboolean#

This key toggles whether CloudCannon will allow keys without values to imply a value of true when parsing key-value pairs in snippet parameters.

Setting this key to true will allow keys to be specified without values, which will be interpreted as true.

By default, this key is false (i.e., keys without values are not allowed).

Show examplesHide examples

In this example, we have configured snippet format to allow implied values for keys without values.

Copied to clipboard

_snippets:
  example:
    snippet: <<example [[param]]>>
    params:
      param:
        parser: argument
        options:
          format:
            allow_implied_values: true

{
  "_snippets": {
    "example": {
      "snippet": "<<example [[param]]>>",
      "params": {
        "param": {
          "parser": "argument",
          "options": {
            "format": {
              "allow_implied_values": true
            }
          }
        }
      }
    }
  }
}

allow_nullboolean#

This key toggles whether CloudCannon will allow null values when parsing snippet parameters.

Setting this key to true will allow null values in snippet parameter parsing.

By default, this key is false (i.e., null values are not allowed).

Show examplesHide examples

In this example, we have configured snippet format to allow null values in parameter parsing.

Copied to clipboard

_snippets:
  example:
    snippet: <<example [[param]]>>
    params:
      param:
        parser: argument
        options:
          format:
            allow_null: true

{
  "_snippets": {
    "example": {
      "snippet": "<<example [[param]]>>",
      "params": {
        "param": {
          "parser": "argument",
          "options": {
            "format": {
              "allow_null": true
            }
          }
        }
      }
    }
  }
}

allow_numbersboolean#

This key toggles whether CloudCannon will allow unquoted numbers like 5 and -0.4 when parsing snippet parameters.

Setting this key to true will allow unquoted numeric values in snippet parameter parsing.

By default, this key is false (i.e., unquoted numbers are not allowed).

Show examplesHide examples

In this example, we have configured snippet format to allow unquoted numbers.

Copied to clipboard

_snippets:
  example:
    snippet: <<example [[param]]>>
    params:
      param:
        parser: argument
        options:
          format:
            allow_numbers: true

{
  "_snippets": {
    "example": {
      "snippet": "<<example [[param]]>>",
      "params": {
        "param": {
          "parser": "argument",
          "options": {
            "format": {
              "allow_numbers": true
            }
          }
        }
      }
    }
  }
}

allowed_string_casesObject#

This key defines which string case types are allowed when parsing snippet parameters.

The value is an object that can contain any, leading_upper, leading_lower, lower, or upper properties. Each property is a boolean that enables or disables that case type.

Show examplesHide examples

In this example, we have configured snippet format to allow only lowercase strings.

Copied to clipboard

_snippets:
  example:
    snippet: <<example [[param]]>>
    params:
      param:
        parser: argument
        options:
          format:
            allowed_string_cases:
              lower: true

{
  "_snippets": {
    "example": {
      "snippet": "<<example [[param]]>>",
      "params": {
        "param": {
          "parser": "argument",
          "options": {
            "format": {
              "allowed_string_cases": {
                "lower": true
              }
            }
          }
        }
      }
    }
  }
}

array_boundaryObject#

This key defines the characters that start and end array literals when parsing snippet parameters.

The value is an object that contains start and end properties, each specifying a string token. For arrays, this will usually be { start: "[", end: "]" }.

Show examplesHide examples

In this example, we have configured array boundaries to use square brackets.

Copied to clipboard

_snippets:
  example:
    snippet: <<example [[param]]>>
    params:
      param:
        parser: argument
        options:
          format:
            array_boundary:
              start: '['
              end: ']'

{
  "_snippets": {
    "example": {
      "snippet": "<<example [[param]]>>",
      "params": {
        "param": {
          "parser": "argument",
          "options": {
            "format": {
              "array_boundary": {
                "start": "[",
                "end": "]"
              }
            }
          }
        }
      }
    }
  }
}

array_delimiterstring#

This key defines the delimiter that separates each value from the next within an array when parsing snippet parameters.

The value is a string that specifies the delimiter token. If required, this will usually be ,.

Show examplesHide examples

In this example, we have configured array delimiter to use a comma.

Copied to clipboard

_snippets:
  example:
    snippet: <<example [[param]]>>
    params:
      param:
        parser: argument
        options:
          format:
            array_boundary:
              start: '['
              end: ']'
            array_delimiter: ','

{
  "_snippets": {
    "example": {
      "snippet": "<<example [[param]]>>",
      "params": {
        "param": {
          "parser": "argument",
          "options": {
            "format": {
              "array_boundary": {
                "start": "[",
                "end": "]"
              },
              "array_delimiter": ","
            }
          }
        }
      }
    }
  }
}

forbidden_tokensArray<forbidden_tokens[*]>#

This key defines tokens that stop parsing content as soon as they are encountered when parsing snippet parameters.

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
          format:
            forbidden_tokens:
              - <

{
  "_snippets": {
    "highlight": {
      "snippet": "<<highlight>> [[content]] <</highlight>>",
      "params": {
        "content": {
          "parser": "content",
          "options": {
            "editor_key": "highlighted_text",
            "format": {
              "forbidden_tokens": [
                "<"
              ]
            }
          }
        }
      }
    }
  }
}

object_boundaryObject#

This key defines the characters that start and end object literals when parsing snippet parameters.

The value is an object that contains start and end properties, each specifying a string token. For objects, this will usually be { start: "{", end: "}" }.

Show examplesHide examples

In this example, we have configured object boundaries to use curly braces.

Copied to clipboard

_snippets:
  example:
    snippet: <<example [[param]]>>
    params:
      param:
        parser: argument
        options:
          format:
            object_boundary:
              start: '{'
              end: '}'

{
  "_snippets": {
    "example": {
      "snippet": "<<example [[param]]>>",
      "params": {
        "param": {
          "parser": "argument",
          "options": {
            "format": {
              "object_boundary": {
                "start": "{",
                "end": "}"
              }
            }
          }
        }
      }
    }
  }
}

object_pair_delimiterstring#

This key defines the delimiter that separates each key-value pair from the next within an object when parsing snippet parameters.

The value is a string that specifies the delimiter token. If required, this will usually be ,.

Show examplesHide examples

In this example, we have configured object pair delimiter to use a comma.

Copied to clipboard

_snippets:
  example:
    snippet: <<example [[param]]>>
    params:
      param:
        parser: argument
        options:
          format:
            object_boundary:
              start: '{'
              end: '}'
            object_pair_delimiter: ','

{
  "_snippets": {
    "example": {
      "snippet": "<<example [[param]]>>",
      "params": {
        "param": {
          "parser": "argument",
          "options": {
            "format": {
              "object_boundary": {
                "start": "{",
                "end": "}"
              },
              "object_pair_delimiter": ","
            }
          }
        }
      }
    }
  }
}

object_value_delimiterstring#

This key defines the delimiter that separates a key from its value within an object when parsing snippet parameters.

The value is a string that specifies the delimiter token. If required, this will usually be :.

Show examplesHide examples

In this example, we have configured object value delimiter to use a colon.

Copied to clipboard

_snippets:
  example:
    snippet: <<example [[param]]>>
    params:
      param:
        parser: argument
        options:
          format:
            object_boundary:
              start: '{'
              end: '}'
            object_value_delimiter: ':'

{
  "_snippets": {
    "example": {
      "snippet": "<<example [[param]]>>",
      "params": {
        "param": {
          "parser": "argument",
          "options": {
            "format": {
              "object_boundary": {
                "start": "{",
                "end": "}"
              },
              "object_value_delimiter": ":"
            }
          }
        }
      }
    }
  }
}

remove_empty_root_boundaryboolean#

This key toggles whether CloudCannon will remove root boundary tokens from the source code when a key-value segment is empty.

Setting this key to true will remove root boundary tokens when the segment is empty.

By default, this key is false (i.e., root boundary tokens are not removed when segments are empty).

Show examplesHide examples

In this example, we have configured snippet format to remove empty root boundaries from source code.

Copied to clipboard

_snippets:
  example:
    snippet: <<example [[param]]>>
    params:
      param:
        parser: argument
        options:
          format:
            remove_empty_root_boundary: true

{
  "_snippets": {
    "example": {
      "snippet": "<<example [[param]]>>",
      "params": {
        "param": {
          "parser": "argument",
          "options": {
            "format": {
              "remove_empty_root_boundary": true
            }
          }
        }
      }
    }
  }
}

root_boundaryObject#

This key defines the boundary tokens required for key-value segments when parsing snippet parameters.

The value is an object that contains start and end properties, each specifying a string token. This defines paired tokens that enclose the root parameter structure.

Show examplesHide examples

In this example, we have configured root boundaries to use angle brackets.

Copied to clipboard

_snippets:
  example:
    snippet: <<example [[param]]>>
    params:
      param:
        parser: argument
        options:
          format:
            root_boundary:
              start: '<<'
              end: '>>'

{
  "_snippets": {
    "example": {
      "snippet": "<<example [[param]]>>",
      "params": {
        "param": {
          "parser": "argument",
          "options": {
            "format": {
              "root_boundary": {
                "start": "<<",
                "end": ">>"
              }
            }
          }
        }
      }
    }
  }
}

root_pair_delimiterArray<root_pair_delimiter[*]>#

This key defines the delimiters that separate each key-value pair from the next when parsing snippet parameters.

The value is an array of strings, where each string specifies a delimiter token. For segments such as href="about" title="Hello World", this would be [" "] (a space). For segments such as href: about, title: "Hello World", this would be [","].

Show examplesHide examples

In this example, we have configured root pair delimiter to use a space.

Copied to clipboard

_snippets:
  example:
    snippet: <<example [[param]]>>
    params:
      param:
        parser: argument
        options:
          format:
            root_pair_delimiter:
              - ' '

{
  "_snippets": {
    "example": {
      "snippet": "<<example [[param]]>>",
      "params": {
        "param": {
          "parser": "argument",
          "options": {
            "format": {
              "root_pair_delimiter": [
                " "
              ]
            }
          }
        }
      }
    }
  }
}

root_value_boundaryObject#

This key defines the boundary tokens required for arguments and values when parsing snippet parameters.

The value is an object that contains start and end properties, each specifying a string token. For example, MDX specifies { start: "{", end: "}" }, which allows syntax such as <Component flag={true} />.

Show examplesHide examples

In this example, we have configured root value boundaries to use curly braces.

Copied to clipboard

_snippets:
  example:
    snippet: <<example [[param]]>>
    params:
      param:
        parser: argument
        options:
          format:
            root_value_boundary:
              start: '{'
              end: '}'

{
  "_snippets": {
    "example": {
      "snippet": "<<example [[param]]>>",
      "params": {
        "param": {
          "parser": "argument",
          "options": {
            "format": {
              "root_value_boundary": {
                "start": "{",
                "end": "}"
              }
            }
          }
        }
      }
    }
  }
}

root_value_boundary_optionalObject<root_value_boundary_optional.*>#

This key defines which value types do not require root value boundaries when parsing snippet parameters.

The value is an object where each property key is a value type name and each property value is a boolean. When set to true, that value type does not require root value boundaries. For example, MDX specifies { string: true }, which allows strings to exist as <Component arg="true" /> rather than <Component arg={"true"} />.

Show examplesHide examples

In this example, we have configured root value boundaries to be optional for strings.

Copied to clipboard

_snippets:
  example:
    snippet: <<example [[param]]>>
    params:
      param:
        parser: argument
        options:
          format:
            root_value_boundary_optional:
              string: true

{
  "_snippets": {
    "example": {
      "snippet": "<<example [[param]]>>",
      "params": {
        "param": {
          "parser": "argument",
          "options": {
            "format": {
              "root_value_boundary_optional": {
                "string": true
              }
            }
          }
        }
      }
    }
  }
}

root_value_delimiterstring#

This key defines the delimiter that separates a key from its value in key-value pairs when parsing snippet parameters.

The value is a string that specifies the delimiter token. For pairs such as key="value", this would be =. For pairs such as key: "value", this would be : .

Show examplesHide examples

In this example, we have configured root value delimiter to use an equals sign.

Copied to clipboard

_snippets:
  example:
    snippet: <<example [[param]]>>
    params:
      param:
        parser: argument
        options:
          format:
            root_value_delimiter: '='

{
  "_snippets": {
    "example": {
      "snippet": "<<example [[param]]>>",
      "params": {
        "param": {
          "parser": "argument",
          "options": {
            "format": {
              "root_value_delimiter": "="
            }
          }
        }
      }
    }
  }
}

string_boundaryArray<string_boundary[*]>#

This key defines the valid tokens that can bound a string when parsing snippet parameters.

The value is an array of strings, where each string specifies a valid boundary token. The parser will ensure the matched end token is the same as the start token. To handle common strings with either single or double quotes, this would usually be ["'", "\""].

Show examplesHide examples

In this example, we have configured string boundaries to allow single and double quotes.

Copied to clipboard

_snippets:
  example:
    snippet: <<example [[param]]>>
    params:
      param:
        parser: argument
        options:
          format:
            string_boundary:
              - '"'
              - ''''

{
  "_snippets": {
    "example": {
      "snippet": "<<example [[param]]>>",
      "params": {
        "param": {
          "parser": "argument",
          "options": {
            "format": {
              "string_boundary": [
                "\"",
                "'"
              ]
            }
          }
        }
      }
    }
  }
}

string_escape_characterstring#

This key defines the character that can be placed before a string boundary to escape it when parsing snippet parameters.

The value is a string that specifies the escape character. If required, this will usually be \.

Show examplesHide examples

In this example, we have configured string escape character to use a backslash.

Copied to clipboard

_snippets:
  example:
    snippet: <<example [[param]]>>
    params:
      param:
        parser: argument
        options:
          format:
            string_escape_character: \\

{
  "_snippets": {
    "example": {
      "snippet": "<<example [[param]]>>",
      "params": {
        "param": {
          "parser": "argument",
          "options": {
            "format": {
              "string_escape_character": "\\\\"
            }
          }
        }
      }
    }
  }
}

Examples:

A common option to configure for the argument parser is the string_boundary:

Copied to clipboard

_snippets:
  video:
    snippet: <<video [[video_arg]]>>
    params:
      video_arg:
        parser: argument
        options:
          model:
            editor_key: video_id
          format:
            string_boundary:
              - '"'
              - '`'

{
  "_snippets": {
    "video": {
      "snippet": "<<video [[video_arg]]>>",
      "params": {
        "video_arg": {
          "parser": "argument",
          "options": {
            "model": {
              "editor_key": "video_id"
            },
            "format": {
              "string_boundary": [
                "\"",
                "`"
              ]
            }
          }
        }
      }
    }
  }
}

This would make our snippet match <<video "CZcNgDN81Sw">> or <<video `CZcNgDN81Sw`>> but not <<video 'CZcNgDN81Sw'>> or <<video CZcNgDN81Sw>>.

Another common requirement is specifying forbidden_tokens, especially when defining an argument with no string boundary.

Copied to clipboard

_snippets:
  video:
    snippet: <<video [[video_arg]]>>
    params:
      video_arg:
        parser: argument
        options:
          model:
            editor_key: video_id
          format:
            forbidden_tokens:
              - '>'
            string_boundary:
              - ''

{
  "_snippets": {
    "video": {
      "snippet": "<<video [[video_arg]]>>",
      "params": {
        "video_arg": {
          "parser": "argument",
          "options": {
            "model": {
              "editor_key": "video_id"
            },
            "format": {
              "forbidden_tokens": [
                ">"
              ],
              "string_boundary": [
                ""
              ]
            }
          }
        }
      }
    }
  }
}

User Articles

User Guides

User Glossary

Developer Articles

Developer Guides

Developer Reference

Snippet Format

Table of contents