_snippets_definitions

Description:

A record of reusable values that can be referenced in snippet templates. Values are substituted using { ref: "key" } for direct replacement or { spread_ref: "key" } for spreading arrays/objects. Common definition types include parser formats, argument models, select option lists, and simple string values like shortcode names.

Type:

Object<Snippet Definition Value>

Values:

Snippet FormatObject#

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.

Show examplesHide 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": [
                ""
              ]
            }
          }
        }
      }
    }
  }
}

Snippet ModelObject#

This key defines the parsing configuration for this argument.

Parser Model ArrayArray<Snippet Model>#

An array of parser model configurations. Typically used for positional_args or named_args definitions that specify the arguments a snippet accepts. Each model defines an argument's editor key, type, default value, and whether it's optional.

Select Values ArrayArray<Snippet Definition Select Value>#

An array of select option values. Commonly used for language lists in code highlighting snippets, where each option has a display name and a value. For example: [{ name: "JavaScript", value: "js" }, { name: "Python", value: "python" }].

String Valuestring#

A string value definition. Commonly used for shortcode_name, tag_name, content_key, include_name, and similar definitions that identify snippet components by name.

Number Valuenumber#

A numeric value definition. Use for counts, sizes, or other numeric values that can be referenced in snippet templates.

Boolean Valueboolean#

A boolean value definition. Use for flags and toggles that can be referenced in snippet templates.

String ArrayArray<snippet-definition-value(string-array)[*]>#

An array of string values. Useful for defining lists of allowed values, delimiters, or other string collections that can be referenced in snippet templates.

Examples:

Define reusable values like shortcode names, argument models, and parser formats that can be referenced in snippet templates.

Copied to clipboard

_snippets_definitions:
  shortcode_name: highlight
  content_key: content
  positional_args:
    - editor_key: language
      type: string
    - editor_key: linenos
      type: boolean
      optional: true
      default: false
  custom_format:
    root_pair_delimiter:
      - ' '
    root_value_delimiter: '='
    string_boundary:
      - '"'
      - ''''
      - ''
    allow_booleans: true
    allow_numbers: true

{
  "_snippets_definitions": {
    "shortcode_name": "highlight",
    "content_key": "content",
    "positional_args": [
      {
        "editor_key": "language",
        "type": "string"
      },
      {
        "editor_key": "linenos",
        "type": "boolean",
        "optional": true,
        "default": false
      }
    ],
    "custom_format": {
      "root_pair_delimiter": [
        " "
      ],
      "root_value_delimiter": "=",
      "string_boundary": [
        "\"",
        "'",
        ""
      ],
      "allow_booleans": true,
      "allow_numbers": true
    }
  }
}

Reference definitions in snippet templates using { ref: "key" } syntax. This allows you to reuse common configurations across multiple snippets.

Copied to clipboard

_snippets_definitions:
  shortcode_name: figure
  named_args:
    - editor_key: src
      type: string
    - editor_key: alt
      type: string
      optional: true
_snippets_templates:
  my_shortcode_template:
    snippet: '{{< [[name]] [[args]] >}}'
    params:
      name:
        parser: literal
        options:
          literal:
            ref: shortcode_name
      args:
        parser: key_values
        options:
          models:
            ref: named_args
_snippets:
  figure:
    template: my_shortcode_template
    definitions:
      shortcode_name: figure
      named_args:
        - editor_key: src
          type: string
        - editor_key: alt
          type: string

{
  "_snippets_definitions": {
    "shortcode_name": "figure",
    "named_args": [
      {
        "editor_key": "src",
        "type": "string"
      },
      {
        "editor_key": "alt",
        "type": "string",
        "optional": true
      }
    ]
  },
  "_snippets_templates": {
    "my_shortcode_template": {
      "snippet": "{{< [[name]] [[args]] >}}",
      "params": {
        "name": {
          "parser": "literal",
          "options": {
            "literal": {
              "ref": "shortcode_name"
            }
          }
        },
        "args": {
          "parser": "key_values",
          "options": {
            "models": {
              "ref": "named_args"
            }
          }
        }
      }
    }
  },
  "_snippets": {
    "figure": {
      "template": "my_shortcode_template",
      "definitions": {
        "shortcode_name": "figure",
        "named_args": [
          {
            "editor_key": "src",
            "type": "string"
          },
          {
            "editor_key": "alt",
            "type": "string"
          }
        ]
      }
    }
  }
}

Define a list of select options for use in snippet inputs, such as a list of programming languages for a code highlighting snippet.

Copied to clipboard

_snippets_definitions:
  languages:
    - name: JavaScript
      value: js
    - name: Python
      value: python
    - name: Ruby
      value: ruby
    - name: HTML
      value: html
    - name: CSS
      value: css

{
  "_snippets_definitions": {
    "languages": [
      {
        "name": "JavaScript",
        "value": "js"
      },
      {
        "name": "Python",
        "value": "python"
      },
      {
        "name": "Ruby",
        "value": "ruby"
      },
      {
        "name": "HTML",
        "value": "html"
      },
      {
        "name": "CSS",
        "value": "css"
      }
    ]
  }
}

User Articles

User Guides

User Glossary

Developer Articles

Developer Guides

Developer Reference

`_snippets_definitions`

Table of contents