Skip to content

Templating

Jump to bottom
Alejandro edited this page Mar 1, 2025 · 5 revisions

Templating Guide

Norgolith uses the Tera templating engine to generate HTML from your Norg content. This guide will walk you through creating, customizing, and extending templates for your Norgolith site.

Template Basics

Templates in Norgolith are written in HTML with Tera's templating syntax. They are stored in the templates/ directory of your site or theme.

Default Templates

  • base.html: The base template that other templates extend.
  • index.html: The homepage template.

Example: Basic Template

<!-- templates/post.html -->
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>{{ metadata.title }}</title>
</head>
<body>
    <h1>{{ metadata.title }}</h1>
    <div class="content">{{ content }}</div>
</body>
</html>

Template Variables

Norgolith provides several variables for use in your templates:

  • metadata: Frontmatter data from the Norg file.
  • config: Global site configuration from norgolith.toml
  • content: The rendered HTML content.

Example

<!-- templates/post.html -->
<h1>{{ metadata.title }}</h1>
<div class="content">{{ content }}</div>

Template Inheritance

Use template inheritance to avoid duplicating code. For example:

<!-- templates/base.html -->
<html>
  <head>
    <title>{{ site.title }}</title>
  </head>
  <body>
    {% block content %}{% endblock %}
  </body>
</html>

<!-- templates/post.html -->
{% extends "base.html" %}

{% block content %}
  <h1>{{ metadata.title }}</h1>
  <div class="content">{{ content }}</div>
{% endblock %}

Filters and Functions

Tera comes with some built-in global filters and functions which you can use directly in your templates. Additionally, Norgolith also exposes custom Tera functions for use in templates:

  • now(): Returns the current datetime.
<!-- Usage examples -->
{{ now() }}       {# Basic version #}
{{ now(format="%Y-%m-%d") }}  {# Custom format version #}

Advanced Templating Techniques

Loops and Conditionals

Tera supports loops and conditionals for dynamic content.

Example: Looping Over Categories

<ul>
    {% for category in metadata.categories %}
        <li>{{ category }}</li>
    {% endfor %}
</ul>

Example: Conditional Rendering

{% if metadata.draft %}
    <div class="draft-notice">This post is a draft.</div>
{% endif %}

Including Partial Templates

You can include other templates within a template.

Example: Including a Header

{% include "header.html" %}

Practical Examples

Example 1: Blog Post Template

<!-- templates/post.html -->
{% extends "base.html" %}

{% block content %}
    <article>
        <h1>{{ metadata.title }}</h1>
        <p class="meta">By {{ metadata.author }} on {{ metadata.created_at | date("%Y-%m-%d") }}</p>
        <div class="content">{{ content }}</div>
        <ul class="categories">
            {% for category in metadata.categories %}
                <li>{{ category }}</li>
            {% endfor %}
        </ul>
    </article>
{% endblock %}

Example 2: Homepage Template

<!-- templates/index.html -->
{% extends "base.html" %}

{% block content %}
    <section class="posts">
        {% for post in site.posts %}
            <article>
                <h2><a href="{{ post.url }}">{{ post.title }}</a></h2>
                <p class="meta">By {{ post.author }} on {{ post.created_at | date("%Y-%m-%d") }}</p>
                <div class="excerpt">{{ post.excerpt }}</div>
            </article>
        {% endfor %}
    </section>
{% endblock %}

Troubleshooting Template Issues

Common Issues and Fixes

Template Not Rendering

  • Ensure the template file is in the correct directory (templates/).
  • Check for syntax errors in your Tera templates.

Missing Variables

  • Verify that the variable exists in the context (e.g., metadata.title).
  • Check for typos in variable names.

Inheritance Errors

  • Ensure the base template exists and is correctly referenced.
  • Verify that {% block %} tags are correctly placed.

Best Practices

Organizing Templates

  • Keep templates modular and reusable.
  • Use template inheritance to avoid duplicating code.
  • Organize partial templates into subdirectories (e.g. templates/partials/).

Clone this wiki locally