Skip to main content

Questions and Answers

Short answers to questions that come up once you start writing templates, each with a link to the page that explains it properly.

Do I need to learn a special syntax?​

For plain value replacement, only a placeholder such as Pebble's own {{ varName }} (or a style you declare under placeholders, such as ___varName___). Under the hood CodeBaker uses the Pebble Template Engine (Twig-like syntax) for everything dynamic: filters, conditionals, loops and expressions (see Pebble Syntax). To keep the file valid for your IDE, put the Pebble tag in a one-line comment that starts with CodeBaker:, for example //CodeBaker: {% if condition %}.

The accepted comment prefixes are //, /* */, #, -- and <!-- --> (the closing */ or --> is optional). The directive must be the last thing on its line. Plain // is not a CSS comment, so in CSS write /* CodeBaker: ... */. More in Template Basics.

What if my files already contain {{ }} or {% %}, like Vue, Twig, Blade or Jinja?​

Pebble reads every {{ }} and {% %} in a template, so text that must reach the generated file as it is needs protection. You have two options:

  • Protect only those places. Wrap them in a raw block: <!-- CodeBaker: {% raw %} --> before and <!-- CodeBaker: {% endraw %} --> after. Pebble, your declared placeholders and replace rules all skip what is inside. See Preserving Code from Processing.
  • Choose other delimiters for the whole template. Put syntax: "square" in codebaker.config.json5 and CodeBaker reads [[ name ]] and [% if x %] instead, so every {{ }} and {% %} stays plain text. The choice covers file contents, file names, the mapping file, directives and slot markers. Pick a set your files do not use themselves: square is a poor fit for JSON or Python with nested lists, TOML tables and bash [[ ]], and angle for ERB, EJS and JSP. See syntax.

What is the difference between placeholders and syntax?​

placeholders adds an extra way to write a value, such as ___title___, which is turned into {{ title }} before Pebble runs. Pebble still reads {{ }} and {% %} as usual. syntax changes the delimiters Pebble itself reads, for the whole template, so {{ }} and {% %} become plain text. Use placeholders when a placeholder does not suit a language or your IDE, and syntax when your files already contain {{ }} or {% %}. You can use both together. See placeholders or syntax?.

Can I update just one part of a file that already exists?​

Yes, with an insert entry. You mark a slot in the target file ({% slot menu %} ... {% endslot %}, bare or inside a comment), and each generation adds its fragment to the slot or updates the fragment it added before. Nothing else in the file is touched. See insert.

Why did the text I typed into a slot disappear?​

An insert goes into the generated result, not into the file already on disk. A file that is an ordinary template file is written again from the template on every run, so a slot starts from what the template contains (usually nothing). To keep the file, and everything you typed in it, from one run to the next, make it a seed entry: it is written once, and the insert then updates only its own fragment. An insert never removes anything it did not put there; to empty a slot deliberately, use type: "replace".

Do I need a seed before I use json-upsert?​

No. A JSON list can always start empty, so if the target file does not exist, json-upsert creates it and adds the first entry. That is different from insert, which needs a slot that already exists in the file. Add a seed only if the document must start with other data. See json-upsert.

Can json-upsert add to a list inside a bigger JSON file?​

Yes, with path, for example path: "#/groups/admin/entities". The missing parts are created, and everything else in the file stays as it was. A json-upsert that could only work by throwing existing data away (an object with no path, or a value of the wrong kind on the path) stops with a message instead. See path.

What if the file json-upsert writes to already exists and is not JSON?​

The generation stops with a message that names the file and says the content is not valid JSON5, and the file is not changed. If the JSON sits inside a script, such as const ENTITIES = [...];, declare the surrounding text with wrapperPrefix and wrapperSuffix. See If the target exists and is not JSON.

How do I control the indentation of what is inserted?​

Use the indent option of the entry. By default ("auto") the fragment follows the neighboring line inside the slot, and an empty slot gets the indentation of the slot's own line. "auto:2" indents the first content of an empty slot 2 more, and plain numbers such as 0, 2 or -2 are counted from the slot's line. See the indentation table in insert.