nixtml

Collections are used to group, paginate, and list related content (like blog posts or portfolio pieces). When you define a collection, nixtml automatically:

1. Gathers content from a specified directory.
2. Sorts items by date (newest first).
3. Creates pagination pages for browsing items.
4. Generates RSS feeds for syndication.
5. Creates taxonomy pages for tags, categories, etc.

nixtml supports two templating approaches: simple String Templates and Functional HTML. Functional HTML is the preferred method because it provides structure and helps prevent typos by using a library of predefined HTML tags.

To use Functional HTML, you import tags from lib.tags and use them as functions that take attributes and children. This approach allows you to build complex, nested HTML structures using Nix expressions.

inherit (lib.tags) html head body header main footer nav div section article h1 h2 h3 p span a ul ol li meta link time img;

# Usage example
html [ (attrs.lang "en") ] [
  head [] [
    (title "My Page")
  ]
  body [] [
    (h1 [] [ "Hello World" ])
  ]
]

The path option determines both the source directory for content and the location of pagination pages. Pagination pages are created in the parent directory of the specified path.

nixtml offers two ways to define templates using Nix functions:

1. String Templates (Simple): Uses standard Nix string interpolation. This is best for simple, static HTML structures where you just need to inject content.

2. Functional HTML (Type-safe): Uses a library of tag functions (e.g., html, body, div) to construct markup. This approach is more robust and provides a structured way to build complex layouts using Nix logic.

# 1. String Template Example
website.layouts.base = { path, content, ... }: ''
  <!DOCTYPE html>
  <html>
    <body>${content}</body>
  </html>
'';

# 2. Functional HTML Example
website.layouts.base = { path, content, ... }: 
  html [] [
    (head [] [ (title "My Website") ])
    (body [] [ content ])
  ];

Taxonomy pages and RSS feeds follow a predictable URL pattern based on your collection's path. The general pattern is: /{collection-prefix}/{taxonomy}/{term}/.

Example 1: Collection path is blog/posts

• Tag page (nix): /blog/tags/nix/index.html
• Paginated tag page: /blog/tags/nix/page/2/index.html
• RSS feed for nix: /blog/tags/nix/index.xml
• Category page: /blog/categories/tutorials/index.html

Example 2: Collection path is posts

• Tag page (nix): /tags/nix/index.html
• RSS feed for nix: /tags/nix/index.xml

nixtml supports YAML frontmatter in Markdown files. The fields defined in the frontmatter are parsed and made available in your templates via the metadata object.

---
title: Page Title
date: 2026-01-19T00:00:00
customField: any value
---

Content here...

---
title: Home
date: 2026-01-19T00:00:00
---

# Welcome to My Website

Taxonomies allow users to browse content by categories or tags. To enable them, add the desired frontmatter keys to your taxonomies list in the collection configuration. nixtml will generate index pages and RSS feeds for each term.

website.collections.blog = {
  path = "blog/posts";
  taxonomies = [ "tags" "categories" ];
};

To avoid repeating markup, you can define reusable components called partials within your website.layouts configuration. Partials are typically functions that accept an argument object (like pageTitle or item) and return a list of HTML elements.

In a complete setup, you can inherit these partials from config.website.layouts.partials to use them within your main layout templates (like base, home, or page).

website.layouts = {
  # Define partials
  partials = {
    header = { }: 
      header [ (attrs.class "site-header") ] [
        (div [ (attrs.class "container") ] [ (a [ (attrs.href "/") ] [ "Logo" ]) ])
      ];
  };

  # Use partials in a layout
  base = { content, ... }: 
    html [] [
      (body [] [
        (partials.header {}) # Calling the partial
        content
      ])
    ];
};

To build your website, run the following command:

nix build .#

This generates a result symlink containing your static files (e.g., index.html, sitemap.xml).

To run a local development server, use the serve app defined in your flake.nix:

nix run .#serve

By default, the server runs at http://localhost:8080.

nixtml is a static website generator written in Nix. To use it, you must have Nix installed with flakes enabled.

To enable flakes, add the following to your ~/.config/nix/nix.conf:

experimental-features = nix-command flakes

Once configured, you can create a new project by initializing a directory with a flake.nix file that uses nixtml.lib.mkWebsite.

mkdir my-website
cd my-website