Skip to content

Commit d3e114e

Browse files
arnargarnarg
committed
docs: add documentation content
1 parent 021bd0e commit d3e114e

8 files changed

Lines changed: 2041 additions & 1 deletion

File tree

‎docs/content/.gitkeep‎

Whitespace-only changes.

‎docs/content/collections.md‎

Lines changed: 491 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/content/index.md‎

Lines changed: 382 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,382 @@
1+
---
2+
title: Getting Started with nixtml
3+
date: 2026-01-19T21:00:00
4+
description: A step-by-step guide to creating your first website with nixtml
5+
---
6+
7+
nixtml is a static website generator written in Nix, inspired by Hugo. This guide will walk you through creating your first website from scratch.
8+
9+
## Prerequisites
10+
11+
- **Nix** installed with flakes enabled
12+
- Basic familiarity with Nix language
13+
- A text editor
14+
15+
To enable flakes, add this to your `~/.config/nix/nix.conf`:
16+
17+
```
18+
experimental-features = nix-command flakes
19+
```
20+
21+
## Project Structure
22+
23+
By the end of this guide, your project will look like this:
24+
25+
```
26+
my-website/
27+
├── flake.nix # Main configuration
28+
├── content/
29+
│ ├── index.md # Homepage
30+
│ └── about.md # About page
31+
└── static/ # Static assets (CSS, images, etc.)
32+
└── css/
33+
└── style.css
34+
```
35+
36+
## Step 1: Create a New Project
37+
38+
```bash
39+
mkdir my-website
40+
cd my-website
41+
```
42+
43+
## Step 2: Create the Flake Configuration
44+
45+
Create a `flake.nix` file:
46+
47+
```nix
48+
{
49+
description = "My website generated using nixtml.";
50+
51+
inputs = {
52+
nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
53+
flake-utils.url = "github:numtide/flake-utils";
54+
nixtml.url = "github:arnarg/nixtml";
55+
};
56+
57+
outputs = {
58+
self,
59+
nixpkgs,
60+
flake-utils,
61+
nixtml,
62+
}:
63+
flake-utils.lib.eachDefaultSystem (
64+
system:
65+
let
66+
pkgs = import nixpkgs { inherit system; };
67+
in
68+
{
69+
packages.default = nixtml.lib.mkWebsite {
70+
inherit pkgs;
71+
72+
name = "my-website";
73+
baseURL = "https://my-website.com";
74+
75+
# Site-wide metadata available in templates
76+
metadata = {
77+
lang = "en";
78+
title = "My Website";
79+
description = "Welcome to my website";
80+
};
81+
82+
# Directory containing markdown content
83+
content.dir = ./content;
84+
85+
# Optional: Directory for static assets
86+
# static.dir = ./static;
87+
88+
# Import layout configuration from separate file
89+
imports = [ ./layouts.nix ];
90+
};
91+
92+
# Convenient local development server
93+
apps.serve = {
94+
type = "app";
95+
program =
96+
(pkgs.writeShellScript "serve" ''
97+
echo "Serving at http://localhost:8080"
98+
${pkgs.python3}/bin/python -m http.server -d ${self.packages.${system}.default} 8080
99+
'').outPath;
100+
};
101+
}
102+
);
103+
}
104+
```
105+
106+
## Step 3: Create the Layouts
107+
108+
Create a `layouts.nix` file to define how your pages look:
109+
110+
```nix
111+
{ lib, config, ... }:
112+
let
113+
# Access site metadata defined in flake.nix
114+
inherit (config.website) metadata;
115+
116+
# Import HTML helper functions
117+
inherit (lib.tags)
118+
html
119+
head
120+
body
121+
div
122+
h1
123+
p
124+
a
125+
nav
126+
ul
127+
li
128+
meta
129+
;
130+
inherit (lib.tags) title link;
131+
inherit (lib) attrs;
132+
in
133+
{
134+
website.layouts = {
135+
# Base template wraps all pages
136+
base = { path, content, ... }:
137+
"<!DOCTYPE html>\n"
138+
+ (html [ (attrs.lang metadata.lang) ] [
139+
(head [] [
140+
(meta [ (attrs.charset "UTF-8") ])
141+
(meta [
142+
(attrs.name "viewport")
143+
(attrs.content "width=device-width, initial-scale=1.0")
144+
])
145+
(meta [
146+
(attrs.name "description")
147+
(attrs.content metadata.description)
148+
])
149+
(title metadata.title)
150+
# Uncomment when you add static/css/style.css
151+
# (link [
152+
# (attrs.rel "stylesheet")
153+
# (attrs.href "/css/style.css")
154+
# ])
155+
])
156+
(body [] [
157+
(nav [] [
158+
(ul [] [
159+
(li [] [ (a [ (attrs.href "/") ] [ "Home" ]) ])
160+
(li [] [ (a [ (attrs.href "/about") ] [ "About" ]) ])
161+
])
162+
])
163+
(div [ (attrs.class "container") ] [ content ])
164+
])
165+
]);
166+
167+
# Template for index.md (homepage)
168+
home = { content, ... }: content;
169+
170+
# Template for all other pages
171+
page = { metadata, content, ... }: [
172+
(h1 [] [ metadata.title ])
173+
content
174+
];
175+
176+
# Required for collections (can be minimal for now)
177+
collection = { pageNumber, totalPages, items, ... }:
178+
(div [] [
179+
(ul [] (map (item: li [] [ item.title ]) items))
180+
"Page ${toString pageNumber} of ${toString totalPages}"
181+
]);
182+
183+
# Required for taxonomies (can be minimal for now)
184+
taxonomy = { title, pageNumber, totalPages, items, ... }:
185+
(div [] [
186+
(h1 [] [ title ])
187+
(ul [] (map (item: li [] [ item.title ]) items))
188+
"Page ${toString pageNumber} of ${toString totalPages}"
189+
]);
190+
};
191+
}
192+
```
193+
194+
## Step 4: Create Content
195+
196+
Create the content directory and your first pages:
197+
198+
```bash
199+
mkdir -p content
200+
```
201+
202+
### Homepage (`content/index.md`)
203+
204+
```markdown
205+
---
206+
title: Home
207+
date: 2026-01-19T00:00:00
208+
---
209+
210+
# Welcome to My Website
211+
212+
This is the homepage of my nixtml-powered website.
213+
214+
Built with **Nix** for reproducible, declarative static site generation.
215+
```
216+
217+
### About Page (`content/about.md`)
218+
219+
```markdown
220+
---
221+
title: About
222+
date: 2026-01-19T00:00:00
223+
---
224+
225+
This website was created using nixtml, a static site generator written in Nix.
226+
227+
## Why nixtml?
228+
229+
- Declarative configuration
230+
- Reproducible builds
231+
- Native Nix integration
232+
- Markdown content with frontmatter
233+
```
234+
235+
## Step 5: Build Your Website
236+
237+
```bash
238+
nix build .#
239+
```
240+
241+
This creates a `result` symlink pointing to your built website. Explore the output:
242+
243+
```bash
244+
ls -la result/
245+
```
246+
247+
You should see:
248+
249+
- `index.html` - Your homepage
250+
- `about/index.html` - Your about page
251+
- `sitemap.xml` - Auto-generated sitemap
252+
253+
## Step 6: Serve Locally
254+
255+
```bash
256+
nix run .#serve
257+
```
258+
259+
Open [http://localhost:8080](http://localhost:8080) in your browser to see your website.
260+
261+
## Step 7: Add Styling (Optional)
262+
263+
Create a static directory with CSS:
264+
265+
```bash
266+
mkdir -p static/css
267+
```
268+
269+
Create `static/css/style.css`:
270+
271+
```css
272+
* {
273+
box-sizing: border-box;
274+
}
275+
276+
body {
277+
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
278+
line-height: 1.6;
279+
color: #333;
280+
max-width: 800px;
281+
margin: 0 auto;
282+
padding: 20px;
283+
}
284+
285+
nav ul {
286+
list-style: none;
287+
padding: 0;
288+
display: flex;
289+
gap: 20px;
290+
border-bottom: 1px solid #eee;
291+
padding-bottom: 10px;
292+
margin-bottom: 20px;
293+
}
294+
295+
nav a {
296+
text-decoration: none;
297+
color: #0066cc;
298+
}
299+
300+
nav a:hover {
301+
text-decoration: underline;
302+
}
303+
304+
h1 {
305+
color: #111;
306+
}
307+
308+
.container {
309+
padding: 20px 0;
310+
}
311+
```
312+
313+
Then update your `flake.nix` to include static files:
314+
315+
```nix
316+
# Uncomment this line in mkWebsite:
317+
static.dir = ./static;
318+
```
319+
320+
And uncomment the stylesheet link in `layouts.nix`.
321+
322+
Rebuild to see the changes:
323+
324+
```bash
325+
nix run .#serve
326+
```
327+
328+
## Understanding the Configuration
329+
330+
### `mkWebsite` Options
331+
332+
| Option | Description |
333+
|--------|-------------|
334+
| `name` | Website name (used in derivation name) |
335+
| `baseURL` | Full URL where site will be hosted |
336+
| `metadata` | Arbitrary data available in all templates |
337+
| `content.dir` | Directory containing markdown files |
338+
| `static.dir` | Directory with static assets |
339+
| `layouts` | Template functions for rendering pages |
340+
| `imports` | Additional Nix modules to import |
341+
342+
### Template Context
343+
344+
Each template receives a context object:
345+
346+
- **base**: `{ path, content, ... }` - receives rendered content from child templates
347+
- **home**: `{ content, metadata, ... }` - receives parsed markdown content
348+
- **page**: `{ content, metadata, ... }` - receives parsed markdown content
349+
- **collection**: `{ pageNumber, totalPages, items, hasNext, hasPrev, ... }`
350+
- **taxonomy**: `{ title, taxonomoy, pageNumber, totalPages, items, hasNext, hasPrev, ... }`
351+
352+
### Frontmatter
353+
354+
Markdown files support YAML frontmatter:
355+
356+
```markdown
357+
---
358+
title: Page Title
359+
date: 2026-01-19T00:00:00
360+
customField: any value
361+
---
362+
363+
Content here...
364+
```
365+
366+
The frontmatter is available as `metadata` in your templates.
367+
368+
## Next Steps
369+
370+
Now that you have a basic website running:
371+
372+
- **[Collections](/nixtml/collections)**: Create a blog with pagination and RSS feeds
373+
- **[Taxonomies](/nixtml/taxonomies)**: Organize content with tags and categories
374+
- **[Advanced Templating](/nixtml/templating)**: Master the Nix HTML library and partials
375+
- **[Nixtml Module Options](/nixtml/options)**: View all available module options in nixtml
376+
377+
## Complete Example
378+
379+
See the [examples directory](https://github.com/arnarg/nixtml/tree/main/examples) in the nixtml repository for complete working examples:
380+
381+
- **simple**: Basic website with pages
382+
- **blog**: Full blog with collections, taxonomies, and RSS feeds

0 commit comments

Comments
 (0)