One of the most common pitfalls when working with Go’s text/template and html/template packages—and a frequent stumbling block for AI agents—is understanding how whitespace manipulation works. Specifically, the - (minus sign) in {{- and -}} is highly meaningful. It is not just decorative syntax or a continuation of the {{ token; it explicitly clears whitespace.

If you aren’t careful with these markers, you can quickly ruin the formatting of output that relies on strict whitespace, such as YAML or cleanly indented HTML.

In this post, we will explore intelligent techniques for managing whitespace in Go templates to ensure your output looks exactly as intended.

The Meaning of the Minus Sign

When you use {{-, you are instructing the template engine to trim all preceding whitespace (spaces, tabs, carriage returns, and newlines) up to the previous non-whitespace character. Conversely, -}} trims all subsequent whitespace up to the next non-whitespace character.

Often, developers mistakenly use {{- and -}} symmetrically, clearing whitespace in both directions. This frequently leads to text being smushed together across lines.

Best Practice: Generally, try to clear whitespace in only one direction. If you only need to clear the newline before a block, use {{-. If you only need to clear the newline after, use -}}.

Intelligent Whitespace Techniques

Beyond simply adding - to your action tags, here are several advanced techniques for precisely controlling whitespace:

1. The Empty Comment Trick (Use Sparingly)

You can use an empty comment combined with whitespace trimming to manipulate spacing without outputting any content. Note: This should generally be considered a last resort, as it introduces extraneous elements into the template source code that don’t relate to the actual data being rendered.

  • Clear everything: Use {{- /**/ -}} to completely strip all whitespace surrounding this block.
  • Stop clearing: Use {{ /**/ }} (without the minus signs) to act as a barrier. The template engine will evaluate it and output nothing, but any whitespace around it will be preserved because there are no - markers to trim it.

2. Enforcing Exact Whitespace

Sometimes you need to guarantee a specific amount of whitespace, regardless of what surrounds the template tag. You can achieve this by outputting literal string values.

  • Exact Spaces: Use {{- " " -}} to clear all surrounding dynamic whitespace and replace it with exactly two spaces. The - clears the existing whitespace, and the string literal " " guarantees your desired spacing.
  • Dynamic Spacing with Printf: For larger or dynamically sized spacing, you can use the printf function. For example, {{- printf "%20s" "" -}} will clear surrounding whitespace and insert exactly 20 spaces.
    • You can also pipe output directly into printf for padding variables: {{- .MyValue | printf "%20s" -}} (or equivalently {{- printf "%20s" .MyValue -}}).

The Two-Way Readability Rule

A golden rule of template design is that templates must be two-way readable. This means:

  1. The resulting output must be perfectly formatted for its target language (like YAML or JSON).
  2. The template source code itself must remain human-readable and maintainable.

If you rely heavily on template functions like | indent or densely pack conditions onto single lines, do so intelligently. Overusing these can make the template source incredibly difficult to decipher. Strive for a balance where the template’s structure mirrors the output’s structure as much as possible.

Best Practices Around if Statements and Examples

Conditionals in templates ({{ if .Condition }}) are notorious for introducing unwanted blank lines. This is particularly destructive when generating formats like YAML, where consistent indentation and spacing are strictly required.

When using if statements, pay close attention to which direction you are clearing. Let’s look at some examples of what can go wrong and how to fix it.

Example 1: The Symmetrical Smush (Bad)

If you blindly apply {{- and -}} everywhere, you might unintentionally strip the required newline and indentation for the YAML keys, causing invalid syntax.

Template Input:

1resources:
2  {{- if .Requests -}}
3  requests:
4    cpu: 100m
5  {{- end -}}

Resulting Output:

1resources:requests:
2    cpu: 100m

Why it’s bad: The {{- if .Requests -}} stripped the newline before requests:, smushing resources: and requests: onto the same line, resulting in invalid YAML.

Example 2: The Blank Line Bleed (Bad)

If you don’t use the minus signs at all, skipped conditions will leave behind blank lines.

Template Input:

1resources:
2  {{ if .Requests }}
3  requests:
4    cpu: 100m
5  {{ end }}
6  {{ if .Limits }}
7  limits:
8    memory: 256Mi
9  {{ end }}

Resulting Output (if .Requests is false, but .Limits is true):

1resources:
2
3  limits:
4    memory: 256Mi

Why it’s bad: The skipped requests block leaves behind a blank line. While sometimes valid in YAML, excessive blank lines can break lists or make the file harder to read.

Example 3: The Unidirectional Clear (Good)

Instead, it is often best to leave the newline after the condition to preserve the indentation of the inner block, and use {{- before the if and end tags to consume the trailing newlines from the previous blocks.

Template Input:

1resources:
2{{- if .Requests }}
3  requests:
4    cpu: 100m
5{{- end }}
6{{- if .Limits }}
7  limits:
8    memory: 256Mi
9{{- end }}

Resulting Output (if .Requests is false, but .Limits is true):

1resources:
2  limits:
3    memory: 256Mi

Why it’s good: The {{- on the if and end lines ensures that if a block is skipped, no empty lines are left behind. At the same time, it preserves the structural indentation and line breaks required by the output format when the condition is met. The template is also highly readable.

Testing Template Output Automatically

Testing template generation is critical, especially when outputting strict formats. Visual inspection isn’t enough; you need automated verification.

1. Structural Parsing Verification

The most robust way to ensure your template didn’t produce a “symmetrical smush” or break indentation is to actually parse the resulting output. If you are generating YAML or JSON, unmarshal the bytes back into a Go struct or a generic map[string]any as part of your unit test.

1func TestYAMLTemplate(t *testing.T) {
2	// ... execute template into a bytes.Buffer ...
3
4	// Verify it actually parses as valid YAML
5	var output map[string]any
6	if err := yaml.Unmarshal(buf.Bytes(), &output); err != nil {
7		t.Fatalf("Template produced invalid YAML: %v\nOutput was:\n%s", err, buf.String())
8	}
9}

2. Byte-to-Byte Accuracy with txtar

For ensuring the exact formatting and spacing remains identical across refactors, use byte-to-byte comparison against known-good fixtures. The txtar format (from golang.org/x/tools/txtar) is excellent for this. It allows you to package your template input data and the expected template output in a single file.

When doing exact string comparisons, always normalize line endings first to avoid cross-platform test failures (e.g., Windows \r\n vs Linux \n).

1// Normalize newlines before comparing
2got := strings.ReplaceAll(buf.String(), "\r\n", "\n")
3expected := strings.ReplaceAll(string(archive.Files["expected.yaml"].Data), "\r\n", "\n")

3. Displaying Meaningful Diffs

When a byte-to-byte test fails, printing “got != expected” is useless for debugging whitespace. You must display a diff.

There are two common approaches:

  • External Libraries: Using a library like github.com/google/go-cmp/cmp gives you powerful, structured diffing.
  • In-house Split diffs: For simple text, you can split the strings by \n and iterate through the slices to print a side-by-side or inline diff showing exactly which lines differ. You can also explore existing diffing packages like github.com/arran4/golang-diff which provide various diffing algorithms and output formats (like unified diffs) to make whitespace errors obvious.

Mastering these whitespace techniques and pairing them with rigorous parsing and diff-based testing will make your template engine much more robust.