Functions

Built-in functions for retrieving data and generating URLs in templates.

Data Retrieval

get_page()

Retrieve any page by path or URL:

{% set about = get_page(path="about.md") %}
{% if about %}
<a href="{{ about.url }}">{{ about.title }}</a>
{% endif %}

Parameters:

Returns: Page? (nil if not found)

Returned Properties:

Examples:

{# Page in root #}
{% set contact = get_page(path="contact.md") %}

{# Page in section #}
{% set intro = get_page(path="docs/introduction.md") %}

{# Match by URL #}
{% set intro_by_url = get_page(path="/docs/introduction/") %}

get_section()

Retrieve a section by section name, source path, or URL:

{% set blog = get_section(path="blog") %}
{% if blog %}
<h2>{{ blog.title }}</h2>
<ul>
{% for p in blog.pages %}
  <li><a href="{{ p.url }}">{{ p.title }}</a></li>
{% endfor %}
</ul>
{% endif %}

Parameters:

Returns: Section? (nil if not found)

Returned Properties:

Examples:

{# Top-level section #}
{% set docs = get_section(path="docs") %}

{# Nested section #}
{% set guides = get_section(path="docs/guides") %}

{# Match by URL #}
{% set blog = get_section(path="/blog/") %}

{# Display count #}
<p>{{ docs.pages_count }} articles</p>

get_taxonomy()

Access taxonomy terms and their pages:

{% set tags = get_taxonomy(kind="tags") %}
{% if tags %}
<ul class="tag-cloud">
{% for term in tags.items %}
  <li>
    <a href="/tags/{{ term.slug }}/">
      {{ term.name }} ({{ term.count }})
    </a>
  </li>
{% endfor %}
</ul>
{% endif %}

Parameters:

Returns: Taxonomy? (nil if not found)

Returned Properties:

Term Properties:

get_taxonomy_url()

Generate URL for a taxonomy term:

<a href="{{ get_taxonomy_url(kind='tags', term='crystal') }}">
  Crystal articles
</a>

Parameters:

Returns: String (absolute URL)

Data Loading

load_data()

Load external data files (JSON, TOML, YAML, CSV):

{% set menu = load_data(path="data/menu.json") %}
{% for item in menu %}
<a href="{{ item.url }}">{{ item.title }}</a>
{% endfor %}

Parameters:

Returns: Parsed data or nil

Supported Formats:

Examples:

JSON (data/team.json):

[
  {"name": "Alice", "role": "Developer"},
  {"name": "Bob", "role": "Designer"}
]

{% set team = load_data(path="data/team.json") %}
<ul>
{% for member in team %}
  <li>{{ member.name }} - {{ member.role }}</li>
{% endfor %}
</ul>

TOML (data/social.toml):

[[links]]
name = "Twitter"
url = "https://twitter.com/example"

{% set social = load_data(path="data/social.toml") %}
{% for link in social.links %}
<a href="{{ link.url }}">{{ link.name }}</a>
{% endfor %}

Environment

env()

Read environment variables in templates:

{{ env("ANALYTICS_ID") }}
{{ env("API_KEY", default="none") }}

Parameters:

Returns: String (env var value, default, or empty string)

If the variable is not set and no default is provided, an empty string is returned and a build warning is logged.

Examples:

{# Google Analytics #}
{% if env("GA_ID") %}
<script async src="https://www.googletagmanager.com/gtag/js?id={{ env("GA_ID") }}"></script>
{% endif %}

{# API endpoint with fallback #}
<script>
  const API = "{{ env("API_URL", default="https://api.example.com") }}";
</script>

URL Functions

url_for()

Generate URL with base_url:

<a href="{{ url_for(path='/about/') }}">About</a>
<img src="{{ url_for(path='/images/logo.png') }}">

Parameters:

Returns: String (absolute URL)

get_url()

Alias for url_for(). You can use either name:

<a href="{{ get_url(path='/about/') }}">About</a>

asset()

Resolve a bundled or fingerprinted asset to its final URL. When the asset pipeline is enabled, the input name is looked up in the build manifest so you always get the hashed filename.

<link rel="stylesheet" href="{{ asset(name='main.css') }}">
<script src="{{ asset(name='app.js') }}"></script>

Parameters:

Returns: String — absolute URL under base_url. When no manifest entry is found, the name is returned as a path under base_url unchanged, so templates keep working before you turn the pipeline on.

asset_url()

Alias for asset(). Use whichever reads better in your templates.

now()

Get current datetime:

{# Default format #}
<p>Generated: {{ now() }}</p>

{# Custom format #}
<p>Year: {{ now(format="%Y") }}</p>
<p>Date: {{ now(format="%B %d, %Y") }}</p>

Parameters:

Returns: String

Format Codes:

Media Functions

resize_image()

Returns a resized image variant. When image processing is enabled, this returns the URL to an automatically generated resized image. Otherwise, it returns the original URL.

{% set img = resize_image(path="/images/hero.jpg", width=640) %}
<img src="{{ img.url }}" width="{{ img.width }}">

Parameters:

Returns: Object with properties:

The function selects the closest available width from the configured widths. If you request width=500 and the configured widths are [320, 640, 1024], it returns the 640px variant (smallest width >= requested). If nothing is large enough, it falls back to the largest available.

The lqip and dominant_color properties require [image_processing.lqip] to be enabled. When disabled, they return empty strings.

Examples:

{# Single resized image #}
{% set img = resize_image(path="/images/hero.jpg", width=800) %}
<img src="{{ img.url }}" alt="Hero">

{# Responsive srcset #}
{% set sm = resize_image(path="/images/hero.jpg", width=320) %}
{% set md = resize_image(path="/images/hero.jpg", width=640) %}
{% set lg = resize_image(path="/images/hero.jpg", width=1024) %}
<img
  src="{{ md.url }}"
  srcset="{{ sm.url }} 320w, {{ md.url }} 640w, {{ lg.url }} 1024w"
  sizes="(max-width: 640px) 320px, (max-width: 1024px) 640px, 1024px"
>

{# With page image from front matter #}
{% if page.image %}
  {% set thumb = resize_image(path=page.image, width=320) %}
  <img src="{{ thumb.url }}" alt="{{ page_title }}">
{% endif %}

{# LQIP blur-up placeholder #}
{% set img = resize_image(path="/images/hero.jpg", width=1024) %}
<img
  src="{{ img.url }}"
  style="background-image: url({{ img.lqip }}); background-size: cover;"
  loading="lazy"
  alt="Hero"
>

{# Dominant color placeholder #}
{% set img = resize_image(path="/images/photo.jpg", width=640) %}
<img
  src="{{ img.url }}"
  style="background-color: {{ img.dominant_color }}"
  loading="lazy"
  alt="Photo"
>

Requires [image_processing] to be enabled in config.toml. See Image Processing for setup details.

Best Practices

Always Check for nil

{% set page = get_page(path="featured.md") %}
{% if page %}
{{ page.title }}
{% else %}
<p>Coming soon</p>
{% endif %}

Cache Function Results

{# Good: Single lookup #}
{% set blog = get_section(path="blog") %}
<h2>{{ blog.title }}</h2>
<p>{{ blog.pages_count }} posts</p>

{# Avoid: Multiple lookups #}
<h2>{{ get_section(path="blog").title }}</h2>
<p>{{ get_section(path="blog").pages_count }} posts</p>

Organize Data Files

data/
├── navigation/
│   ├── main.json
│   └── footer.json
├── team.yaml
└── products.toml

See Also

• Data Model — Site, Section, Page types
• Filters — Value transformation