### Initialize Project Directory
Source: https://github.com/arnarg/nixtml/blob/main/docs/content/index.md
Commands to create the base directory structure for a new nixtml website.
```bash
mkdir my-website
cd my-website
```
--------------------------------
### Build and Serve nixtml Website
Source: https://github.com/arnarg/nixtml/blob/main/docs/content/index.md
Commands to build the static site using Nix and serve it locally for development. These commands interact with the project's flake configuration.
```bash
nix build .#
ls -la result/
nix run .#serve
```
--------------------------------
### Configure flake.nix for nixtml
Source: https://github.com/arnarg/nixtml/blob/main/docs/content/index.md
The main configuration file defining site metadata, content directories, and a local development server app.
```nix
{
description = "My website generated using nixtml.";
inputs = {
nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
flake-utils.url = "github:numtide/flake-utils";
nixtml.url = "github:arnarg/nixtml";
};
outputs = {
self,
nixpkgs,
flake-utils,
nixtml,
}:
flake-utils.lib.eachDefaultSystem (
system:
let
pkgs = import nixpkgs { inherit system; };
in
{
packages.default = nixtml.lib.mkWebsite {
inherit pkgs;
name = "my-website";
baseURL = "https://my-website.com";
metadata = {
lang = "en";
title = "My Website";
description = "Welcome to my website";
};
content.dir = ./content;
imports = [ ./layouts.nix ];
};
apps.serve = {
type = "app";
program =
(pkgs.writeShellScript "serve" ''
echo "Serving at http://localhost:8080"
${pkgs.python3}/bin/python -m http.server -d ${self.packages.${system}.default} 8080
'').outPath;
};
}
);
}
```
--------------------------------
### Enable Nix Flakes
Source: https://github.com/arnarg/nixtml/blob/main/docs/content/index.md
Configuration to enable experimental Nix features required for nixtml projects.
```text
experimental-features = nix-command flakes
```
--------------------------------
### Nixtml Complete Blog Setup (flake.nix)
Source: https://github.com/arnarg/nixtml/blob/main/docs/content/collections.md
A comprehensive example of a `flake.nix` file for setting up a blog with Nixtml. It includes input definitions, system configuration, website metadata, content directory, collection settings, and layout imports.
```nix
{
description = "My blog";
inputs = {
nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
flake-utils.url = "github:numtide/flake-utils";
nixtml.url = "github:arnarg/nixtml";
};
outputs = { self, nixpkgs, flake-utils, nixtml }:
flake-utils.lib.eachDefaultSystem (system:
let pkgs = import nixpkgs { inherit system; };
in {
packages.default = nixtml.lib.mkWebsite {
inherit pkgs;
name = "my-blog";
baseURL = "https://my-blog.com";
metadata = {
lang = "en";
title = "My Blog";
description = "Thoughts on Nix and programming";
};
content.dir = ./content;
collections.blog = {
path = "blog/posts";
pagination.perPage = 5;
taxonomies = [ "tags" ];
rss.enable = true;
};
imports = [ ./layouts.nix ];
};
}
);
}
```
--------------------------------
### Define Website Layouts
Source: https://github.com/arnarg/nixtml/blob/main/docs/content/index.md
A Nix-based layout configuration using HTML helper functions to define the structure of pages, collections, and taxonomies.
```nix
{ lib, config, ... }:
let
inherit (config.website) metadata;
inherit (lib.tags) html head body div h1 p a nav ul li meta title link;
inherit (lib) attrs;
in
{
website.layouts = {
base = { path, content, ... }:
"\n"
+ (html [ (attrs.lang metadata.lang) ] [
(head [] [
(meta [ (attrs.charset "UTF-8") ])
(meta [ (attrs.name "viewport") (attrs.content "width=device-width, initial-scale=1.0") ])
(meta [ (attrs.name "description") (attrs.content metadata.description) ])
(title metadata.title)
])
(body [] [
(nav [] [
(ul [] [
(li [] [ (a [ (attrs.href "/") ] [ "Home" ]) ])
(li [] [ (a [ (attrs.href "/about") ] [ "About" ]) ])
])
])
(div [ (attrs.class "container") ] [ content ])
])
]);
home = { content, ... }: content;
page = { metadata, content, ... }: [
(h1 [] [ metadata.title ])
content
];
collection = { pageNumber, totalPages, items, ... }:
(div [] [
(ul [] (map (item: li [] [ item.title ]) items))
"Page ${toString pageNumber} of ${toString totalPages}"
]);
taxonomy = { title, pageNumber, totalPages, items, ... }:
(div [] [
(h1 [] [ title ])
(ul [] (map (item: li [] [ item.title ]) items))
"Page ${toString pageNumber} of ${toString totalPages}"
]);
};
}
```
--------------------------------
### Configure Static Assets and Styling
Source: https://github.com/arnarg/nixtml/blob/main/docs/content/index.md
Instructions for adding CSS styles and configuring the static directory in the project's flake.nix file. This allows for custom visual themes.
```bash
mkdir -p static/css
```
```css
* {
box-sizing: border-box;
}
body {
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
line-height: 1.6;
color: #333;
max-width: 800px;
margin: 0 auto;
padding: 20px;
}
nav ul {
list-style: none;
padding: 0;
display: flex;
gap: 20px;
border-bottom: 1px solid #eee;
padding-bottom: 10px;
margin-bottom: 20px;
}
nav a {
text-decoration: none;
color: #0066cc;
}
nav a:hover {
text-decoration: underline;
}
h1 {
color: #111;
}
.container {
padding: 20px 0;
}
```
```nix
# Uncomment this line in mkWebsite:
static.dir = ./static;
```
--------------------------------
### Define Markdown Frontmatter
Source: https://github.com/arnarg/nixtml/blob/main/docs/content/index.md
Example of YAML frontmatter used in markdown files to define page metadata. This data is accessible within templates.
```markdown
---
title: Page Title
date: 2026-01-19T00:00:00
customField: any value
---
Content here...
```
--------------------------------
### Configure Nixtml via flake.nix
Source: https://github.com/arnarg/nixtml/blob/main/docs/content/taxonomies.md
A complete example of a flake.nix file configuring a Nixtml website, including metadata, content directory, and collection taxonomies.
```nix
{
inputs = {
nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
flake-utils.url = "github:numtide/flake-utils";
nixtml.url = "github:arnarg/nixtml";
};
outputs = { self, nixpkgs, flake-utils, nixtml }:
flake-utils.lib.eachDefaultSystem (system:
let pkgs = import nixpkgs { inherit system; };
in {
packages.default = nixtml.lib.mkWebsite {
inherit pkgs;
name = "my-blog";
baseURL = "https://my-blog.com";
metadata = {
lang = "en";
title = "My Blog";
};
content.dir = ./content;
collections.blog = {
path = "blog/posts";
pagination.perPage = 5;
taxonomies = [ "tags" "categories" ];
};
imports = [ ./layouts.nix ];
};
}
);
}
```
--------------------------------
### Complete Taxonomy Template Example
Source: https://github.com/arnarg/nixtml/blob/main/docs/content/taxonomies.md
A comprehensive nixtml taxonomy layout that includes a header, post count, a list of post previews (with title, date, and summary), and pagination controls. It utilizes various HTML-like elements provided by nixtml's library.
```nix
{ lib, config, ... }:
let
inherit (lib.tags) div h1 h2 ul li a p span article;
inherit (lib) attrs;
in
{
website.layouts.taxonomy = {
title,
pageNumber,
totalPages,
items,
hasNext,
hasPrev,
nextPageURL,
prevPageURL,
...
}:
[
# Header with term name
(h1 [] [ "Posts tagged: #${title}" ])
# Post count
(p [ (attrs.class "taxonomy-meta") ]
[ "${toString (builtins.length items)} posts" ])
# List of posts
(div [ (attrs.class "post-list") ]
(map (item:
article [ (attrs.class "post-preview") ] [
(h2 [] [
(a [ (attrs.href item.url) ] [ item.title ])
])
(div [ (attrs.class "post-meta") ] [
(span [ (attrs.class "date") ] [ item.date ])
])
(p [ (attrs.class "summary") ] [ item.summary ])
]
) items)
)
# Pagination
(div [ (attrs.class "pagination") ] [
(if hasPrev
then (a [ (attrs.href prevPageURL) (attrs.class "prev") ] [ "← Newer Posts" ])
else (span [ (attrs.class "prev disabled") ] [ "← Newer Posts" ]))
(span [ (attrs.class "page-info") ]
[ "Page ${toString pageNumber} of ${toString totalPages}" ])
(if hasNext
then (a [ (attrs.href nextPageURL) (attrs.class "next") ] [ "Older Posts →" ])
else (span [ (attrs.class "next disabled") ] [ "Older Posts →" ]))
])
];
}
```
--------------------------------
### Structure Markdown Content with Frontmatter
Source: https://context7.com/arnarg/nixtml/llms.txt
Example of a Markdown file structure compatible with nixtml, featuring YAML frontmatter for metadata and the tag for content summarization.
```markdown
---
title: Getting Started with Nix Flakes
date: 2026-01-19T10:00:00
tags:
- nix
- flakes
---
Introduction text.
## What are Flakes?
Flakes provide hermetic evaluation.
```
--------------------------------
### Nix Functional HTML Tag Usage Examples
Source: https://github.com/arnarg/nixtml/blob/main/docs/content/templating.md
Provides examples of how to use tag functions from nixtml's functional HTML library. Each tag function accepts a list of attributes and a list of children, allowing for nested structures and attribute assignment.
```nix
# Examples
(div [] [ "Hello" ]) #
Hello
(div [ (attrs.class "box") ] [ "Hi" ]) #
Hi
(a [ (attrs.href "/") ] [ "Home" ]) # Home
```
--------------------------------
### Nixtml Taxonomy Setup
Source: https://github.com/arnarg/nixtml/blob/main/docs/content/collections.md
Configures Nixtml to generate taxonomy pages (like tags and categories) for content. This involves specifying the content path and the taxonomies to be used.
```nix
website.collections.blog = {
path = "blog/posts";
taxonomies = [ "tags" "categories" ];
};
```
--------------------------------
### Nix Custom Attribute Creation Example
Source: https://github.com/arnarg/nixtml/blob/main/docs/content/templating.md
Demonstrates how to create custom HTML attributes using `lib.mkAttr` in nixtml. This is useful for attributes not pre-defined in the `attrs` library, allowing for flexible attribute generation.
```nix
let
customAttr = lib.mkAttr "data-custom" "value";
in
(div [ customAttr ] [ "Content" ])
#
# Void tags (only attributes, no children)
example5 = meta [ (attrs.charset "UTF-8") ];
# Output:
example6 = link [ (attrs.rel "stylesheet") (attrs.href "/style.css") ];
# Output:
example7 = img [ (attrs.src "/logo.png") (attrs.alt "Logo") ];
# Output:
example8 = br [];
# Output:
# Title convenience function (string instead of list)
example9 = title "My Page Title";
# Output: My Page Title
}
```
--------------------------------
### Configure Content Collections in Nix
Source: https://github.com/arnarg/nixtml/blob/main/README.md
Defines a content collection by specifying the source directory, pagination settings, and RSS generation. This configuration enables automatic generation of paginated listing pages.
```nix
website.collections.blog = {
path = "blog/posts"; # ./content/blog/posts/
pagination.perPage = 5; # Number of items each listing page shows
rss.enable = true; # Generate /blog/index.xml
};
```
--------------------------------
### Access Site Configuration
Source: https://github.com/arnarg/nixtml/blob/main/docs/content/templating.md
Demonstrates how to access site metadata and base URI settings from the configuration object within a Nixtml template.
```nix
{ lib, config, ... }:
let
# Access website configuration
inherit (config.website) metadata baseURL baseURI;
# metadata contains your custom fields
siteTitle = metadata.title;
siteLang = metadata.lang;
# URLs
fullUrl = baseURL; # "https://example.com"
basePath = baseURI; # "/" or "/blog/" if baseURL has path
in
{
website.layouts.base = { path, content, ... }:
...;
}
```
--------------------------------
### Enable Taxonomies for Collections
Source: https://github.com/arnarg/nixtml/blob/main/README.md
Extends a collection configuration to include taxonomies like tags or series. This allows nixtml to generate index pages for specific terms.
```nix
website.collections.blog = {
path = "blog/posts";
taxonomies = [ "tags" "series" ];
};
```
--------------------------------
### Access Template Context Variables
Source: https://github.com/arnarg/nixtml/blob/main/README.md
Lists the available attributes provided to collection and taxonomy layout templates. These variables facilitate pagination and navigation within the generated site.
```nix
{
# --- collection & taxonomy -------------
pageNumber, # Current page number
totalPages, # Total amount of pages
items, # List of posts in this page
hasNext, # A next page exists (bool)
hasPrev, # A previous page exists (bool)
nextPageURL, # URL to next page
prevPageURL, # URL to previous page
# --- only taxonomy --------------------
title, # The tag or term being shown
}
```
--------------------------------
### Implement String-based Templates
Source: https://context7.com/arnarg/nixtml/llms.txt
Uses Nix string interpolation to define website layouts, providing a simpler alternative to the functional HTML library.
```nix
{ lib, config, ... }:
let
inherit (config.website) metadata;
in {
website.layouts = {
base = { path, content, ... }: ''
${metadata.title}
${content}
'';
collection = { pageNumber, totalPages, items, ... }: ''
example8 = br [];
# Output: