2.1 – File or configuration

A box’s content comes from a file or straight from the configuration:

options:
  file: snippet.html   # -> snippets/snippet.html

options:
  html: "<p>Notes from a small town.</p>"

html always wins

With both present, file is not even read. That does not deserve an error message, but it is a common confusion: someone creates a file, it does not appear, and an html from an earlier attempt is still sitting in the entry.

When to use which

	File (file)	Configuration (html)
Size	more than two or three lines	one-liners
Editing	in an editor, with syntax highlighting	in the YAML file, with its escaping rules
In serve mode	a change takes effect on reload	a change needs a restart
In a template package	travels through the Static files part	travels inside the entry itself

The last point surprises people most often — and it is why the Example template for QuartzControl fills six of its seven boxes with html: a template package without the Static files part does not carry snippet files, and a file: box then pointed at nothing in the target project.

YAML and markup get along moderately

Multi-line HTML in YAML needs a block scalar. | keeps the line breaks, >- folds them into spaces and swallows the last one:

options:
  html: |
    <p>First line.</p>
    <p>Second line.</p>

As soon as quotation marks, colons and hash signs appear in the markup — which is to say almost always — a file is the calmer way.