Squiggly

URL & text helpers

2026-05-10T23:04:32.478538713Z

These helpers cover the common things a static site generator wants — they’re the reason juicer ships with a data map containing baseURL and link. If you’re using squiggly as a generic template engine outside that context, you may not need them.

Function	Arity	What
`relURL`	1	Site-relative URL (prepends the renderer’s `baseURL.path`)
`absURL`	1	Absolute URL (prepends `baseURL.base + baseURL.path`)
`urlEscape`	1	Percent-encode for use in URL paths
`markdownify`	1	Render a markdown string to HTML (uses `io.github.edadma.markdown`)
`emojify`	1	Substitute `:smile:` → 😄 (uses `io.github.edadma.emoji`)

Examples

{{ '/getting-started/' | relURL }}        /docs/getting-started/
{{ '/getting-started/' | absURL }}        https://example.com/docs/getting-started/

{{ 'Hello **world**' | markdownify }}     Hello <strong>world</strong>

{{ ':rocket: shipped!' | emojify }}       🚀 shipped!

How `relURL` / `absURL` find baseURL

These read con.renderer.data("baseURL") — a BaseURL(base: String, path: String) value the host application puts in the renderer’s data map at construction time:

import io.github.edadma.squiggly.BaseURL

val renderer = new TemplateRenderer(
  data = Map(
    "baseURL" -> BaseURL("https://example.com", "/docs"),
  ),
)

If your data doesn’t supply this, relURL / absURL will throw at template evaluation. Skip them and write the URLs out directly if you don’t need site-rooting.

Strings

2026-05-10T23:04:32.478538713Z

The string builtins. All can be called as a function, a pipe target, or (where the arity allows) a method.

Function	Arity	What
`upper`	1	Uppercase
`lower`	1	Lowercase
`trim`	1	Strip leading + trailing whitespace
`length`	1	Number of characters
`len`	1	Alias for `length` (works on lists / maps too)
`isEmpty`	1	True if length is zero
`nonEmpty`	1	True if length is non-zero
`reverse`	1	Reverse the string
`replace`	3	`replace s 'old' 'new'` — every occurrence
`split`	2	`split s 'sep'` — into a list of strings
`join`	2	`join list 'sep'` — concatenate with separator
`startsWith`	2	`startsWith s 'prefix'`
`endsWith`	2	`endsWith s 'suffix'`
`contains`	2	`contains s 'needle'`
`indexOf`	2	`indexOf s 'needle'` — `-1` when absent
`substring`	3	`substring s start end` — half-open interval
`repeat`	2	`repeat s n` — repeat the string n times

Examples

{{ .title | upper }}                              CSS HOOK
{{ .author | trim | lower | replace ' ' '-' }}    "ed-maxedon"
{{ .body | split '\n' | length }}                 number of lines

{{ if .filename | endsWith '.md' }}               markdown file
{{ if .body | contains '<!--more-->' }}           has a manual summary cut

{{ split .csv ',' | join ' / ' }}                 reformat

Regex

2026-05-10T23:04:32.478538713Z

Regex builtins use Java’s java.util.regex.Pattern syntax (the same flavor as Scala’s Regex).

Function	Arity	What
`matchRE`	2	`matchRE s pattern` — true if the entire string matches
`findRE`	2	`findRE s pattern` — first match’s groups (a list); empty list when no match
`findAllRE`	2	`findAllRE s pattern` — list of group-lists, one per match
`replaceRE`	3	`replaceRE s pattern replacement` — every match replaced; `$1`, `$2`, `$0` work in `replacement`
`splitRE`	2	`splitRE s pattern` — split on every match, returning the in-between pieces

Examples

Validate

{{ if matchRE .email '^[^@]+@[^@]+\.[^@]+$' }}
  valid
{{ else }}
  invalid
{{ end }}

Extract groups

{{ ymd := findRE .date '^(\d{4})-(\d{2})-(\d{2})$' }}
{{ // ymd is a list: [whole-match, year, month, day] }}
{{ if ymd | nonEmpty }}
  year = {{ ymd[1] }}, month = {{ ymd[2] }}, day = {{ ymd[3] }}
{{ end }}

The capture-group behavior was restored in 0.2.3 — earlier 0.2.x lost groups.

Find every match

{{ for m <- findAllRE .body '\\[\\[([^\\]]+)\\]\\]' }}
  {{ m[1] }}        // each capture group's text
{{ end }}

Replace

{{ replaceRE .body '\\b(\\w+) - (\\w+)\\b' '$1 — $2' }}

Split

{{ for chunk <- splitRE .text '\\s+' }}
  {{ chunk }}
{{ end }}

Quickstart

2026-05-10T23:04:32.478538713Z

A template is a string of HTML or text with {{ … }} interpolation. Squiggly’s API has two halves:

TemplateParser — parses a template string into an AST.
TemplateRenderer — renders an AST against a data shape.

import io.github.edadma.squiggly._

val parser   = TemplateParser.default
val renderer = new TemplateRenderer()

val ast = parser.parse(
  """{{ for p <- .pages }}
    |  - {{ p.title | upper }}
    |{{ end }}""".stripMargin,
)

val data = Map(
  "pages" -> List(
    Map("title" -> "Hello"),
    Map("title" -> "Goodbye"),
  ),
)

renderer.render(data, ast)
// =>
//   - HELLO
//   - GOODBYE

That’s it. The any-data shape (Map[String, Any] / List[Any] / scalars) is what data is — anything that can be a YAML / TOML / JSON document fits without translation.

Customizing the renderer

TemplateRenderer takes four optional parameters:

Parameter	What
`partials`	A `TemplateLoader` (`String => Option[TemplateAST]`) used by `{{ partial 'name' . }}`
`blocks`	Mutable `HashMap[String, TemplateAST]` used by `{{ define name }}` / `{{ block name . }}` — pass an existing one if you want to share named blocks across multiple renders
`functions`	Map of custom template functions to merge with the builtin set
`data`	Renderer-wide data — read inside template functions via `con.renderer.data`

val renderer = new TemplateRenderer(
  partials  = name => myPartialMap.get(name),
  functions = TemplateBuiltin.functions ++ myFunctions,
  data      = Map("siteUrl" -> "https://example.com"),
)

Going deeper

Syntax — every form the parser accepts (substitution, control flow, partials, blocks, pipe filters, expressions).
Builtins — the bundled string / list / regex / date functions.

Installation

2026-05-10T23:04:32.478538713Z

Squiggly is published on Maven Central as io.github.edadma:squiggly. Cross-built for JVM, Scala.js, and Scala Native on Scala 3.

sbt

libraryDependencies += "io.github.edadma" %%% "squiggly" % "0.2.3"

%%% selects the right artifact for your active platform. If you only need the JVM build, %% works too.

scala-cli

//> using dep "io.github.edadma::squiggly:0.2.3"

Mill

ivy"io.github.edadma::squiggly:0.2.3"

Requirements

Scala 3.8.3 — squiggly is Scala 3 only. There is no 2.13 backport.
JVM 17+ for the JVM target.
Node 20+ for the Scala.js target.
Clang for the Scala Native target.

Expressions

2026-05-10T23:04:32.478538713Z

Inside {{ … }} you can put any expression. The result is converted to a string and emitted at that position in the output.

Substitution

The simplest expression is a field access. The . prefix references the current data context:

{{ .name }}
{{ .page.title }}
{{ .args[0] }}
{{ .map['some key'] }}

Bare identifiers (no leading .) reference local variables or template parameters.

Literals

{{ 'a string' }}      single-quoted
{{ "a string" }}      double-quoted (interchangeable)
{{ 42 }}              integer
{{ 3.14 }}            floating point
{{ true }}            boolean
{{ false }}
{{ null }}

Operators

Class	Operators
Arithmetic	`+`, `-`, `*`, `/`, `%`
Comparison	`==`, `!=`, `<`, `<=`, `>`, `>=`
Logical	`and`, `or`, `not`
String	`+` (concatenation)
Membership	`in` (e.g., `'foo' in .tags`)

{{ if .count > 10 and .show }}
  Many.
{{ end }}

Function calls

Any function in the renderer’s function map can be called directly. Most builtins are 1-arity and accept a pipe target.

{{ upper .name }}
{{ len .pages }}
{{ replace .text 'foo' 'bar' }}

Pipe syntax

The pipe operator | threads the previous value as the first argument to the next function. These two are equivalent:

{{ .name | upper | trim }}
{{ trim (upper .name) }}

Pipes read left-to-right, which is friendlier than nested calls when you have several transforms.

Method-style calls

Any 1-arity function can be invoked as a method on its receiver:

{{ .name.upper.trim }}
{{ .name | upper | trim }}
{{ trim (upper .name) }}

All three render the same output.

Grouping

Parentheses group expressions and force evaluation order:

{{ (1 + 2) * 3 }}
{{ if (.count > 0) and (.published) }}…{{ end }}

Conditional expression

The C-style ternary, written with then / else keywords for readability:

{{ if .draft then 'DRAFT' else 'LIVE' }}

(Different from the block-form {{ if … }} … {{ end }} — see Control flow.)

Truthiness

A value is truthy unless it’s:

null
false
the empty string ""
the empty list / map
the integer 0 or float 0.0

if, and, or, and not all use this definition.

Debug

2026-05-10T23:04:32.478538713Z

Two functions you reach for when a template isn’t rendering what you thought it would.

Function	Arity	What
`context`	0	Print the entire current data context to the renderer’s output stream
`type`	1	Return the runtime type name of an expression’s value (e.g. `"java.lang.String"`, `"scala.collection.immutable.Map"`)

Examples

{{ context }}

…dumps everything the template can see at this point — the current data, plus locals introduced by enclosing with / for / := blocks. Useful when a field reference unexpectedly renders empty: drop a {{ context }} above it and check whether the field is actually there.

{{ type .page }}
{{ type .page.tags }}
{{ type .page.weight }}

Tells you what concrete class the value is. Helps when an if is taking the wrong branch (because, say, your “boolean” is actually a string "false" from frontmatter).

When you need more

For non-trivial debugging, it’s often easier to print from Scala — write a small inspect: Any => Any template function that printlns its argument and returns it unchanged, then drop {{ inspect .x }} wherever you want a peek. Squiggly’s data-context model means everything in scope is just a Scala value; you have full freedom to instrument it from outside the template.

Dates

2026-05-10T23:04:32.478538713Z

Date/time builtins use Java’s java.time API. Available on JVM and Scala Native (which has a java.time shim) — Scala.js works too via scala-java-time if you pull it in as a dep.

Function	Arity	What
`now`	0	Current `LocalDateTime`
`dateFormat`	2	`dateFormat date pattern` — render a date with a `DateTimeFormatter` pattern
`dateParse`	2	`dateParse string pattern` — parse a string into a date

Examples

{{ now | dateFormat 'yyyy-MM-dd' }}                today
{{ .page.date | dateFormat 'MMMM d, yyyy' }}        December 7, 2025
{{ .page.date | dateFormat 'EEEE' }}                day of week

{{ d := dateParse .feed.pubDate 'EEE, dd MMM yyyy HH:mm:ss Z' }}
{{ d | dateFormat 'yyyy-MM-dd' }}                   re-format

Pattern reference

The patterns are standard java.time.format.DateTimeFormatter patterns — see the JDK reference for the full grammar. Common pieces:

Pattern	Meaning	Example
`yyyy`	Four-digit year	`2025`
`MM`	Zero-padded month	`07`
`MMM`	Short month name	`Jul`
`MMMM`	Full month name	`July`
`dd`	Zero-padded day	`02`
`d`	Day, no padding	`2`
`EEE`	Short weekday	`Mon`
`EEEE`	Full weekday	`Monday`
`HH`	24-hour hour	`14`
`mm`	Minutes	`05`
`ss`	Seconds	`09`
`Z`	Numeric zone	`+0500`
`zzz`	Short zone name	`EST`

Control flow

2026-05-10T23:04:32.478538713Z

Squiggly’s block-form actions wrap a chunk of template content with conditional, iterative, or scoping logic.

`if` / `elif` / `else`

{{ if .draft }}
  <span class="badge">Draft</span>
{{ elif .scheduled }}
  <span class="badge">Scheduled</span>
{{ else }}
  <span class="badge">Live</span>
{{ end }}

elif and else are optional. Truthiness rules are the same as in expressions — see Expressions.

`for`

Two forms — value-only and key-value:

{{ for p <- .pages }}
  <li>{{ p.title }}</li>
{{ end }}

{{ for k, v <- .frontmatter }}
  <dt>{{ k }}</dt><dd>{{ v }}</dd>
{{ end }}

The iteration variable p is bound inside the block; it’s not visible after {{ end }}.

for works on lists and maps. Iterating a string treats it as a list of code-point characters.

else works on for: it runs when the iterable is empty.

{{ for p <- .pages }}
  …
{{ else }}
  No pages yet.
{{ end }}

`with`

with evaluates an expression once and binds it as the current data context for the block. Inside the block, the leading . refers to whatever you passed in.

{{ with .author }}
  <a href="{{ .url }}">{{ .name }}</a>
{{ end }}

If the bound value is falsy, the block doesn’t render at all (and the optional else runs):

{{ with .editor }}
  Edited by {{ .name }}.
{{ else }}
  No editor.
{{ end }}

`match`

Pattern-match an expression against several literal values:

{{ match .status }}
  {{ case 'draft' }}    <span class="warn">Draft</span>
  {{ case 'live' }}     <span class="ok">Live</span>
  {{ case 'archived' }} <span class="muted">Archived</span>
  {{ else }}            <span>Unknown</span>
{{ end }}

The else branch is optional but recommended — it catches unexpected values.

Variable assignment

Inside any block, you can introduce a local with :=:

{{ words := split .body ' ' }}
{{ wordCount := len words }}

This page has {{ wordCount }} words.

The variable is scoped to the enclosing block.

Nesting

All four block forms nest freely:

{{ for p <- .pages }}
  {{ if p.draft }}
    {{ /* skip drafts */ }}
  {{ else }}
    <article>{{ p.title }}</article>
  {{ end }}
{{ end }}

Comments

2026-05-10T23:04:32.478538713Z

Squiggly recognizes a single comment form, started inside an action with //:

{{ // This won't appear in the output. }}

Everything from // to the closing }} is dropped at parse time. Useful for marking why a partial is being called or why a block is empty:

{{ partial 'sidebar' . }}
{{ // sidebar is intentionally rendered before the main column so its
   // search input gets keyboard focus first. }}
{{ block main . }} … {{ end }}

There is no /* … */ style. If you want a multi-line comment, use multiple single-line ones, or wrap in {{ if false }} … {{ end }} (the cost is the parser still walks the unused branch — fine for prose, expensive only if you nest very large templates).

Collections

2026-05-10T23:04:32.478538713Z

Function	Arity	What
`len`	1	Length of a list / map / string
`isEmpty`	1	True iff the collection has zero items
`nonEmpty`	1	True iff the collection has at least one item
`head`	1	First element of a list
`tail`	1	All but the first
`first`	1	Alias for `head`
`last`	1	Last element
`reverse`	1	Reversed copy
`sort`	1	Sorted copy (natural ordering on the elements)
`distinct`	1	Drop duplicates, preserving original order
`compact`	1	Drop `null` and the empty-tuple `()` from a list
`append`	2	`append elem list` — append to the right
`prepend`	2	`prepend elem list` — prepend to the left

Examples

{{ .args | head }}                          first positional arg
{{ .args | tail | join ' ' }}               drop first, rejoin

{{ for n <- .nums | distinct | sort }}      unique then sorted
  {{ n }}
{{ end }}

{{ if .items | nonEmpty }}…{{ end }}        guard against empty list

{{ .tags | append 'featured' | join ' ' }}  add a tag, render

Maps

for k, v <- m iterates a map. Many of the list builtins above work on maps too — len m returns the entry count, isEmpty m checks for an empty map.

To pluck a value by key, use […] indexing in expressions:

{{ .config['baseURL'] }}
{{ .frontmatter.tags }}        // dot syntax works for string keys

Blocks and partials

2026-05-10T23:04:32.478538713Z

Two ways to share template content across multiple files, with quite different shapes.

Partials

A partial is a template loaded by name from a TemplateLoader. The renderer looks up the name through the loader’s String => Option[TemplateAST] callback, then renders the result with whatever data context you pass in.

{{ partial 'topbar' . }}
{{ partial 'page-toc' .page }}
{{ partial 'footer' (with title='Hello') }}

The first argument is a string literal — the name. The second is the data context to render with. Use . to pass the current context unchanged.

Partials are dynamic — looked up at render time, useful when the partial isn’t known until you’ve parsed the templates.

Wire up partials by passing a loader to the renderer:

val partials: TemplateLoader = name => myPartialMap.get(name)
val renderer = new TemplateRenderer(partials = partials)

Define / block

define and block work together to support a “fill-in-the-blanks” layout pattern. A parent template declares slots with {{ block name . }} … {{ end }} (with optional default content). A child template populates those slots with {{ define name }} … {{ end }}.

The renderer’s blocks field is a mutable.HashMap[String, TemplateAST] carrying the bindings; render the child first to populate it, then render the parent.

A two-pass example

baseof.html (the parent layout):

<!DOCTYPE html>
<html>
<head><title>{{ .page.title }}</title></head>
<body>
  <main>
    {{ block content . }}
      <p>Default content</p>
    {{ end }}
  </main>
</body>
</html>

page.html (the child):

{{ define content }}
  <article>
    <h1>{{ .page.title }}</h1>
    {{ .body }}
  </article>
{{ end }}

To render the page:

val parent = parser.parse(baseof)
val child  = parser.parse(page)

val renderer = new TemplateRenderer()

renderer.render(data, child)   // first pass: populates `define` blocks
renderer.render(data, parent)  // second pass: `block content` finds the
                               // populated definition and substitutes

The first render writes nothing visible — its purpose is the define side effect.

This is the pattern juicer uses for its _default/baseof.html + _default/file.html / _default/folder.html layout combinations.

Default content

{{ block name . }} … {{ end }} renders its inner content if no define populated the block.

{{ block sidebar . }}
  <p>No sidebar configured.</p>
{{ end }}

If sidebar was never defined, the default is what gets rendered.

When to pick which

Situation	Use
Reusable fragment with its own data context (header, card, badge)	Partial
“Outer shell” + variable inner content per page kind	define / block
Many similar pages with different bodies	define / block
Optional decorations chosen at render time	Partial

Both compose well — your baseof block can {{ partial 'topbar' . }} inside it.

Squiggly

URL & text helpers

Examples

How relURL / absURL find baseURL

Strings

Examples

Regex

Examples

Validate

Extract groups

Find every match

Replace

Split

Quickstart

Customizing the renderer

Going deeper

Installation

sbt

scala-cli

Mill

Requirements

Expressions

Substitution

Literals

Operators

Function calls

Pipe syntax

Method-style calls

Grouping

Conditional expression

Truthiness

Debug

Examples

When you need more

Dates

Examples

Pattern reference

Control flow

if / elif / else

for

with

match

Variable assignment

Nesting

Comments

Collections

Examples

Maps

Blocks and partials

Partials

Define / block

A two-pass example

Default content

When to pick which

How `relURL` / `absURL` find baseURL

`if` / `elif` / `else`

`for`

`with`

`match`