---

The monolithic Norg static site generator built with Rust. Leverage rust-norg syntax validation with Norg-to-HTML conversion to build static sites from Norg content.

🌟 Features

• Norg-native content with validation via rust-norg
• Tera v2 templates with shortcodes, optional chaining, and rich filters
• C ABI plugin system with Landlock sandboxing (filesystem confinement, timeout, panic isolation)
• Incremental builds via content-hash caching
• Parallel builds powered by Rayon
• SEO out of the box: sitemap.xml, robots.txt, OpenGraph, Twitter Cards
• Built-in backlinks computed automatically from internal Norg links
• Built-in search index (search_index.json + dev server endpoint)
• Asset fingerprinting (blake3 + fingerprint Tera filter)
• Schema validation for content metadata via lith check
• Custom error pages (404.html, 500.html)
• Live preview dev server with hot reload and config hot-reloading
• Plugin sources: install from crates.io, Git repositories, or local paths

⚖️ Comparison with Hugo and Zola

Dimension	Hugo	Zola	Norgolith
Language	Go	Rust	Rust
Templates	Go templates	Tera v2	Tera v2
Content format	Markdown + 5 others	Markdown only	Norg only
Plugin system	None	None	C ABI + Landlock sandbox
Content validation	None	Link checking	rust-norg parser + schemas (lith check)
Syntax highlighting	Built-in (Chroma)	Built-in	Via plugin (tree-sitter)
Image processing	Yes	Yes	Planned
Asset bundling	Yes	No	Planned
Asset fingerprinting	Yes	No	Yes (blake3)
Configuration	TOML / YAML / JSON	TOML	TOML
Multilingual	Yes	Yes	No
Shortcodes	Built-in	Tera v2 components	Tera v2 component()
Custom output	JSON, RSS, etc	RSS, Atom	RSS, Atom
Theme system	Yes	Yes	Yes
Backlinks	No (custom templates)	No	Yes (automatic)
Built-in search	No	Yes	Yes
Build	Parallel (pages)	Parallel	Parallel + incremental

📝 Requirements

Component	Requirement
Build	Rust >= 1.85 (Rust 2024 edition)

⚡ Install

Run cargo install --release --path . to compile and install Norgolith in your ~/.cargo/bin directory.

🔨 AUR

Use Arch User Repository helper to install norgolith-git.

paru -S norgolith-git

📦 Nix Package

For latest release version: nix-shell -p norgolith.

For git version you can add Norgolith to NixOS configuration with flakes.

{inputs={nixpkgs.url="github:NixOS/nixpkgs/nixos-unstable";norgolith.url="github:norgolith/core";};outputs={nixpkgs,norgolith, ... }:
{nixosConfigurations.mysystem=nixpkgs.lib.nixosSystem{modules=[{environment.systemPackages=[norgolith.packages.x86_64-linux.default];}];};};}

📦 Plugin SDK

Install from crates.io into your plugin project:

cargo add norgolith-plugin-sdk

Or build from the flake:

nix build .#norgolith-plugin-sdk

Add it to your NixOS configuration:

environment.systemPackages=[norgolith.packages.x86_64-linux.norgolith-plugin-sdk];

Scaffold a new plugin with lith plugin new my-plugin, which generates plugin.toml, Cargo.toml, and src/lib.rs.

Hooks: pre_build, post_convert, post_render, post_build. Sandboxing: Landlock filesystem confinement, configurable timeout per hook, panic isolation. Logging: plugin_log! macro bridges to Norgolith's tracing pipeline.

The canonical plugin is written in Rust using the SDK:

use norgolith_plugin_sdk::*;register_plugin!("my-plugin",
hooks:[post_render: my_hook]);fnmy_hook(json: serde_json::Value) -> Result<Option<String>,String>{let ctx:TransformContext = serde_json::from_value(json).map_err(|e| e.to_string())?;Ok(Some(ctx.html))}

Plugins use Norgolith's C ABI, so any language that exports C functions can participate. A C plugin looks like:

#include<stdint.h>#include<string.h>#defineHOOK_POST_RENDER 4
typedefchar* (*plugin_fn)(constchar*);
typedefstruct {
uint32_tabi_version;
constchar*name;
constchar*version;
void (*log_fn)(uint32_t, constchar*);
} plugin_info;
char*post_render(constchar*input) {
/* parse input JSON, return modified HTML or NULL */returnNULL;
}
voidnorgolith_plugin_init(plugin_info*info, uint32_t*mask, plugin_fnhooks[4]) {
info->abi_version=1;
info->name="my-c-plugin";
info->version="0.1.0";
*mask=HOOK_POST_RENDER;
hooks[2] =post_render;
}

For Lua, write a small C shim that embeds Lua and dispatches hook calls to a .lua script:

// c-shim.c — compiles to a .so that Norgolith loads#include<lua5.4/lua.h>#include<lua5.4/lauxlib.h>staticlua_State*L;
voidnorgolith_plugin_init(plugin_info*info, uint32_t*mask, plugin_fnhooks[4]) {
L=luaL_newstate();
luaL_dofile(L, "my-plugin.lua");
*mask=HOOK_POST_RENDER;
hooks[2] =&bridge;
}
char*bridge(constchar*input) {
/* push input, call my-plugin.lua's post_render, return result */
}

See sdk/README.md and norgolith.dev/docs/plugins for full documentation.

🤖 MCP Server

Install from crates.io:

cargo install norgolith-mcp

Or build from source:

cargo build --release --manifest-path norgolith-mcp/Cargo.toml

Or build from the flake:

nix build .#norgolith-mcp

Add it to your NixOS configuration:

environment.systemPackages=[norgolith.packages.x86_64-linux.norgolith-mcp];

Configure in your MCP client:

{
"mcp": {
"norgolith": {
"type": "local",
"command": "norgolith-mcp",
"enable": true
}
}
}

Capabilities: resources (norgolith://docs/*), tools (search_docs, read_source). See norgolith-mcp/README.md for details.

🚀 Quick Start

lith init my-site
cd my-site
lith new -k post hello-world
lith dev --open
lith build

📖 Usage

The produced binary is called lith for short.

$ lith --help
The monolithic Norg static site generator
Usage: lith [OPTIONS] <COMMAND>
Commands:
init Initialize a new Norgolith site
theme Theme management
dev Run a site in development mode
new Create a new asset in the site and optionally open it using your preferred system editor. e.g. 'new -k norg post1.norg' -> 'content/post1.norg'
build Build a site for production
plugin Plugin management
check Validate content files against the configured content schema
preview Preview from build result
help Print this message or the help of the given subcommand(s)
Options:
-v, --version Print version
-d, --dir <PROJECT_DIR> Operate on the project in the given directory
-h, --help Print help

🔌 Plugin Development

Norgolith ships a C ABI plugin system. Plugins are shared libraries (.so, .dylib, .dll) loaded at runtime and sandboxed with Landlock.

Hook pipeline:

Content --> pre_build --> post_convert --> Tera render --> post_render --> post_write --> post_build

Plugin install:

lith plugin install ./my-plugin # from local path
lith plugin install norgolith-tree-sitter # from crates.io
lith plugin install --git https://github.com/norgolith/norgolith-tree-sitter.git

Sandboxing: each plugin gets filesystem confinement (configurable: none / read / write / read-write), a per-hook timeout (default 10s), and panic isolation.

See sdk/README.md for the full plugin guide.

❄️ Developing with Nix

The repository includes a Nix flake for development and testing.

nix build .# build, output in result/
nix run .# build and run
nix develop .# dev shell with all dependencies

For Nix-direnv integration, entering the directory activates the dev shell automatically.

📚 Documentation

The documentation site source lives in the docs/ directory. To work on it:

# From repo root, enter dev shell (includes tailwindcss, mprocs).
nix develop
# Build lith
cargo build --release
# Start docs dev servercd docs
mprocs

See docs/README.md for details.

🚀 Community

Join the Neorg community and get help or discuss about the project:

• Discord server

💌 Supporting Norgolith

Developing and maintaining open-source projects takes time and effort. If you find Norgolith valuable and would like to support its continued development, here are some ways you can help:

• Star this repository on GitHub: this helps raise awareness and shows the project is actively maintained.
• Contribute code or documentation: we welcome contributions from the community.
• Spread the word: let others know about Norgolith if you think they might benefit from it.
• Financial Support (Optional): if you'd like to offer financial support, you can consider using my Ko-fi page (linked in the repository). Any amount is greatly appreciated and helps me invest further time in Norgolith's development.

💜 Sponsors

Huge thanks to the project sponsors for supporting my work!

📖 License

This project is licensed under the GNU General Public License v2 (GPLv2). You can find the license details in the LICENSE file.