Skip to main content

The syntax Setting

syntax chooses the delimiters that CodeBaker reads as Pebble for a whole template. Use it when the files you generate already contain {{ }} or {% %} of their own. This page has the sets, how to define your own, and how syntax differs from placeholders. (The other keys of the config file are in the Configuration Reference.)

Type: string or object. Default: "curly", which is Pebble's usual {{ }}, {% %} and {# #}.

Purpose: Choose the delimiters CodeBaker uses for Pebble in this template. Use it when the files you generate already contain {{ }} or {% %} of their own (Vue, Angular, Handlebars, Twig, Blade, Jinja, Go templates, GitHub Actions) and you would rather not wrap every such place in a raw block.

syntax: "square",   // [[ name ]]  [% if x %]  [# note #]

One syntax applies to the whole template, everywhere Pebble is read:

  • file contents and the seed templates;
  • file and folder names (pages/[[entityKey]]/[[entityKey]].html), open, expand and mapping targets;
  • vars values, the json area and codebaker.advanced.json5;
  • CodeBaker: directives (<!-- CodeBaker: [% if x %] -->), raw and verbatim blocks;
  • the slot markers ([% slot menu %], <!-- CodeBaker: [% endslot %] -->).

The old braces then mean nothing: {{ message }} in a Vue file comes out exactly as written, with no raw block. The only setting that cannot use it is syntax itself, which is read before anything is rendered, so it must be plain text.

The sets

NamePrint a valueTagsCommentFitsDoes not fit
curly (also default, pebble){{ x }}{% %}{# #}The defaultVue, Angular, Handlebars, Twig, Blade, Jinja, Go templates
square[[ x ]][% %][# #]Web stacks and most other filesJSON or Python with nested lists ([[1, 2], [3]]), TOML tables ([[table]]), bash [[ ]], Lua, wiki links
angle<< x >><% %><# #>Files without ERB, EJS or JSPERB, EJS, JSP, ASP (<% %>), heredocs and C++ (<<)

The name is not case sensitive. An unknown name is refused, and the message lists the names that exist.

A custom set. Give all three pairs, each as [open, close]:

syntax: {
  print: ["@{", "}@"],
  tag: ["@[", "]@"],
  comment: ["@#", "#@"],
},

A custom set is checked before anything is generated, and an invalid one stops the run with a message that lists every problem:

  • all three of print, tag and comment are required, and nothing else is allowed (so a typo such as prnt is caught);
  • a delimiter is 1 to 8 characters, with no spaces, tabs or line breaks;
  • the opening and the closing text of one pair must differ;
  • no opening delimiter may be the same as, or start with, another opening delimiter (<{ and <{% are ambiguous), and no two closing delimiters may be equal;
  • a delimiter must not contain <!--, -->, /*, */ or //, which CodeBaker reads as comment markers, and must not end (open) or start (close) with -, which is Pebble's whitespace trim mark;
  • finally Pebble itself is asked to read a small test template with the delimiters, which catches anything the rules above do not know about.

A closing delimiter made of ], } or ) is accepted, but it can also be how an expression ends, so leave a space before it: [[ items[0] ]], not [[ items[0]]].

Choose carefully. Pick a set that does not occur in the files you generate. There is no set that suits everything, which is why the choice belongs to each template. Do not choose ${ }: it is used by JavaScript, shell, Terraform, Kotlin and many others.

placeholders or syntax?​

The two settings sound alike but solve different problems.

  • placeholders adds a way to write a value. You declare a style such as ___VAR___, and ___title___ is turned into Pebble's {{ title }} before Pebble runs. Pebble itself is untouched: it still reads {{ }} for values and {% %} for tags, filters and loops. Use it when {{ title }} upsets your IDE in a place such as a CSS value, a PHP variable name or a file name, and an identifier-like ___title___ does not.
  • syntax changes the delimiters Pebble itself reads. {{ }}, {% %} and {# #} give way to another set for the whole template: values, tags, loops, directives, raw blocks and slot markers. The old braces become plain text. Use it when your files already contain {{ }} or {% %} of their own (Vue, Twig, Blade, Jinja, Go templates).
placeholderssyntax
What it changesAn extra way to write a valueThe delimiters of everything Pebble reads
Example___title___[[ title ]], [% if x %], [# note #]
Tags, filters, loopsStill {% %} and {{ x | filter }}Written with the chosen delimiters
Files that contain their own {{ }}No help: Pebble still reads themSolves it: they are plain text
How manyAny number of styles at onceOne set per template
DefaultNone built in (only Pebble's {{ name }})curly, which is {{ }} and {% %}

They are independent, and you can use both. With syntax: "square" and placeholders: ["___VAR___"], a Vue file can contain <h1>___title___</h1>, which becomes the value of title (written as [[ title ]] for Pebble), next to a <p>{{ message }}</p> that comes out untouched.

Which one? If the problem is that a placeholder is not valid in a particular language, declare a placeholder style. If the problem is that the files already use {{ }} or {% %}, choose a syntax. If it is only a few places in a few files, a raw block may be simpler than either.

Next​