Blorg

A flexible static blog / website generation engine.

Installation

npm install blorg

Quick Start

blorg config.json

Where config.json defines your blog structure (see Configuration below).

Directory Structure

A typical blog setup:

my-blog/
├── build.js          # Your build script
├── posts/            # Markdown posts
│   ├── my-first-post.md
│   └── another-post.md
├── templates/        # Nunjucks templates
│   ├── post.html     # Individual post template
│   ├── index.html    # Index/archive template
│   └── feed.xml      # Atom feed template
└── output/           # Generated site (git submodule or deploy target)

Post Format

Posts are markdown files with a JSON metadata header:

{
  "title": "My First Post",
  "date": "2026-01-24",
  "author": "Your Name"
}

Your markdown content here. Supports **GFM** and fenced code blocks
with syntax highlighting.

Metadata Fields

Field	Required	Description
title	Yes	Post title
date	Yes	Publication date (used for sorting)
author	No	Author name
draft	No	Set to true to exclude from output
path	No	Custom URL path (overrides config pattern)
base	No	URL slug (auto-generated from title if omitted)

Any additional fields you add are available in templates via post.spec.yourField.

Custom Paths

By default, posts use the path pattern from config (e.g., /{year}/{month}/{title}.html). Override per-post:

{
  "title": "My Post",
  "date": "2026-01-24",
  "path": "/{title}.html"
}

Path patterns support: {year}, {month}, {title} (the base slug).

Templates

Blorg uses Nunjucks for templating.

post.html

Renders individual posts. Available variables:

Variable	Description
spec	Post metadata object (spec.title, spec.date, spec.author, etc.)
page	Rendered HTML content
date	Build timestamp
postSpecs	Array of all post metadata (for navigation/sidebar)
blogPosts	Array of all posts (full objects)

Example:

{% extends "layout.html" %}

{% block content %}
<article>
  <h1>{{ spec.title }}</h1>
  <time>{{ spec.date | date("F j, Y") }}</time>
  {{ page | safe }}
</article>
{% endblock %}

index.html

Renders index and archive pages. Additional variables:

Variable	Description
posts	Array of posts for this page
nextPage	Next page number (or null)
prevPage	Previous page number (or null)

Example:

{% for post in posts %}
<article>
  <h2><a href="{{ post.spec.path }}">{{ post.spec.title }}</a></h2>
  <time>{{ post.spec.date | date("F j, Y") }}</time>
</article>
{% endfor %}

{% if prevPage !== null %}
<a href="page{{ prevPage }}.html">Newer</a>
{% endif %}
{% if nextPage !== null %}
<a href="page{{ nextPage }}.html">Older</a>
{% endif %}

feed.xml

Atom feed template. Same variables as index, but typically uses blogPosts for all posts.

Configuration

A minimal config.json:

{
  "templateRoot": "./templates/",
  "outputRoot": "./output/",
  "data": [
    {
      "id": "blogPosts",
      "type": "markdown-posts",
      "postRoot": "./posts/",
      "path": "/{year}/{month}/{title}.html"
    },
    {
      "id": "postSpecs",
      "type": "post-specs",
      "blogData": "blogPosts"
    },
    {
      "id": "postTemplate",
      "type": "nunjucks-template",
      "file": "post.html"
    },
    {
      "id": "indexTemplate",
      "type": "nunjucks-template",
      "file": "index.html"
    },
    {
      "id": "feedTemplate",
      "type": "nunjucks-template",
      "file": "feed.xml"
    }
  ],
  "output": [
    {
      "id": "posts",
      "type": "post-files",
      "template": "postTemplate",
      "data": ["date", "blogPosts", "postSpecs"]
    },
    {
      "id": "index",
      "type": "index-files",
      "postsPerPage": 5,
      "indexFile": "index.html",
      "archiveFile": "page{number}.html",
      "template": "indexTemplate",
      "data": ["date", "blogPosts", "postSpecs"]
    },
    {
      "id": "feed",
      "type": "single-file",
      "output": "atom.xml",
      "template": "feedTemplate",
      "data": ["date", "blogPosts"]
    }
  ]
}

Data Sources

Loaded sequentially (order matters - later sources can reference earlier ones).

Type	Description
markdown-posts	Load posts from a directory via ssbl
post-specs	Extract just metadata from loaded posts
nunjucks-template	Compile a Nunjucks template
multi-page-markdown	Load markdown split into pages (for presentations)

Output Processors

Run in parallel after all data is loaded.

Type	Description
single-file	Render one template to one file
post-files	Render each post to its own file
index-files	Render paginated index/archive pages

Programmatic API

For build scripts or integration with other tools:

import Blorg, { archetypes } from 'blorg'
import { fileURLToPath } from 'node:url'
import { dirname } from 'node:path'

const __dirname = dirname(fileURLToPath(import.meta.url))

// Use the blog archetype for sensible defaults
const config = archetypes.blog({
  outputRoot: './output/',
  // Optional overrides:
  // templateRoot: './templates/',
  // postRoot: './posts/',
  // postPath: '/{year}/{month}/{title}.html',
})

const blorg = new Blorg(__dirname, config)
await blorg.run()

Markdown & Syntax Highlighting

Posts are processed with Brucedown:

• GitHub Flavoured Markdown (tables, strikethrough, task lists)
• Shiki syntax highlighting (VS Code quality, 200+ languages)
• Output uses inline styles (no CSS required for code blocks)

Licence

MIT Licence. Copyright (c) Rod Vagg.