rs-web - Static Site Generator

A fast, opinionated static site generator built in Rust with support for:

Markdown processing with syntax highlighting, external link handling
Content encryption (full post or partial :::encrypted blocks)
HTML content files with Tera templating support
Link graph with backlinks and visualization (Obsidian-style)
RSS feed generation with section filtering
Parallel processing for fast builds
Live reload with automatic browser refresh during watch mode
Asset minification for CSS, JS (with dead code elimination), and HTML

Installation

cargo install rs-web

Or with Nix:

nix run github:rslib/web#rs-web

Quick Start

# Build the site
rs-web build

# Build to custom output directory
rs-web build --output public

# Watch for changes and rebuild incrementally with live reload
rs-web build --watch

# Watch mode with custom port
rs-web build --watch --port 8080

Incremental Builds

When using --watch, rs-web tracks file dependencies automatically and only rebuilds what's necessary:

Dependency tracking: All file reads/writes in Lua and Tera are tracked automatically
Smart rebuilds: Only rebuilds when tracked dependencies change
Stale page cleanup: Pages that no longer exist (e.g., renamed tags) are automatically deleted
Change output: Shows which files changed during each rebuild
Live reload: Browser automatically refreshes when content changes
Memoization: Transform functions like render_markdown cache results
Cache persistence: Dependencies are cached in .rs-web-cache/deps.bin

# Watch mode with smart incremental builds and live reload
rs-web build --watch

# Watch mode with custom port
rs-web build --watch --port 8080

# Clean the cache to force a full rebuild
rm -rf .rs-web-cache

Logging

Control log verbosity with --debug, --log-level, or the RS_WEB_LOG_LEVEL environment variable.

# Enable debug logging (shorthand)
rs-web --debug build

# Set specific log level (trace, debug, info, warning, error)
rs-web --log-level trace build

# Use environment variable
RS_WEB_LOG_LEVEL=debug rs-web build

Priority order: --debug > --log-level > RS_WEB_LOG_LEVEL > default (warning)

Configuration

Configure via config.lua:

return {
  site = {
    title = "My Site",
    description = "Site description",
    base_url = "https://example.com",
    author = "Your Name",
  },

  build = {
    output_dir = "dist",
  },

  -- Generate pages via Lua
  pages = function()
    return {
      { path = "/", template = "home.html", title = "Home" },
      { path = "/about/", template = "page.html", title = "About", minify = true },
    }
  end,

  -- Build hooks
  hooks = {
    before_build = function()
      print("Starting build...")
    end,
    after_build = function()
      print("Build complete!")
    end,
  },
}

Lua Sandbox

By default, Lua file operations are sandboxed to the project directory (where config.lua is located). This prevents accidental or malicious access to files outside your project.

return {
  -- Sandbox is enabled by default. Set to false to allow access outside project directory.
  lua = {
    sandbox = false,  -- Disable sandbox (use with caution)
  },

  site = { ... },
}

When sandbox is enabled:

File operations (read_file, write_file, load_json, etc.) only work within the project directory
Attempting to access files outside returns an error with a helpful message
Relative paths are resolved from the project root

Lua API Functions

The rs-web module must be explicitly required:

local rs = require("rs-web")

Available functions:

File System (rs.fs):

Function	Description
`rs.fs.read(path)`	Read file contents, returns nil if not found
`rs.fs.write(path, content)`	Write content to file, returns true/false
`rs.fs.copy(src, dest)`	Copy file (binary-safe), returns true/false
`rs.fs.exists(path)`	Check if file exists
`rs.fs.list(path, pattern?)`	List files matching glob pattern
`rs.fs.list_dirs(path)`	List subdirectories
`rs.fs.glob(pattern)`	Find files matching glob pattern
`rs.fs.scan(dir, pattern?)`	Scan directory recursively

Parallel file operations:

Function	Description
`rs.fs.par.read(paths)`	Read multiple files in parallel
`rs.fs.par.exists(paths)`	Check multiple files exist in parallel
`rs.fs.par.copy(sources, dests)`	Copy multiple files in parallel
`rs.fs.par.create_dirs(paths)`	Create directories in parallel

Data Loading (rs.data):

Function	Description
`rs.data.load_json(path)`	Load and parse JSON file
`rs.data.load_yaml(path)`	Load and parse YAML file
`rs.data.load_toml(path)`	Load and parse TOML file
`rs.data.load_frontmatter(path)`	Extract frontmatter and content from markdown
`rs.data.from_json(str)`	Parse JSON string to Lua value
`rs.data.to_json(value, pretty?)`	Serialize Lua value to JSON string
`rs.data.from_yaml(str)`	Parse YAML string to Lua value
`rs.data.to_yaml(value)`	Serialize Lua value to YAML string
`rs.data.from_toml(str)`	Parse TOML string to Lua value
`rs.data.to_toml(value)`	Serialize Lua value to TOML string

Parallel data operations:

Function	Description
`rs.data.par.load_json(paths)`	Load multiple JSON files in parallel
`rs.data.par.load_yaml(paths)`	Load multiple YAML files in parallel
`rs.data.par.load_frontmatter(paths)`	Parse frontmatter from multiple files in parallel

HTML Processing (rs.html):

Function	Description
`rs.html.to_text(html)`	Convert HTML to plain text
`rs.html.strip_tags(html)`	Remove HTML tags
`rs.html.extract_links(html)`	Extract all links from HTML
`rs.html.extract_images(html)`	Extract all image sources from HTML

Date & Time (rs.date):

All date functions accept: Unix timestamp (number), date string, or table {year, month, day, hour?, min?, sec?}

Function	Description
`rs.date.now()`	Get current Unix timestamp
`rs.date.from_timestamp(ts)`	Convert Unix timestamp to DateTime table
`rs.date.to_timestamp(date)`	Convert date to Unix timestamp
`rs.date.format(date, format)`	Format date using strftime format
`rs.date.parse(str, format?)`	Parse date string to DateTime table (auto-detects or custom format)
`rs.date.rss_format(date)`	Format date for RSS (RFC 2822)
`rs.date.iso_format(date)`	Format date as ISO 8601
`rs.date.add(date, delta)`	Add time: `{years?, months?, days?, hours?, mins?, secs?}`
`rs.date.diff(date1, date2)`	Get difference in seconds

DateTime table: {year, month, day, hour, min, sec, weekday, yday}

Markdown (rs.markdown):

Function	Description
`rs.markdown.render(content, opts?)`	Render markdown to HTML with optional plugins
`rs.markdown.plugins(...)`	Combine/flatten plugins into array
`rs.markdown.plugins.default(opts?)`	Get default plugins (lazy_images, heading_anchors, external_links)
`rs.markdown.plugins.lazy_images(opts?)`	Plugin: add `loading="lazy" decoding="async"` to images
`rs.markdown.plugins.heading_anchors(opts?)`	Plugin: add `id="slug"` to headings
`rs.markdown.plugins.external_links(opts?)`	Plugin: add `target="_blank" rel="noopener"` to external links

Example:

-- Simple (uses default plugins)
local html = rs.markdown.render(content)

-- With custom plugins
local html = rs.markdown.render(content, {
  plugins = rs.markdown.plugins(
    rs.markdown.plugins.default({ lazy_images = false }),
    my_custom_plugin()
  ),
})

-- Custom plugin example
local function highlight_plugin()
  return function(ast)
    local new_ast = {}
    for _, event in ipairs(ast) do
      -- Transform events here
      table.insert(new_ast, event)
    end
    return new_ast
  end
end

Image Processing (rs.image):

Function	Description
`rs.image.dimensions(path)`	Get image width and height
`rs.image.resize(input, output, options)`	Resize image (options: width, height?, quality?)
`rs.image.convert(input, output, options?)`	Convert image format (options: format?, quality?)
`rs.image.optimize(input, output, options?)`	Optimize/compress image (options: quality?)

Parallel image operations:

Function	Description
`rs.image.par.resize(inputs, outputs, options?)`	Resize multiple images in parallel
`rs.image.par.convert(inputs, outputs, options?)`	Convert multiple images in parallel
`rs.image.par.optimize(inputs, outputs, options?)`	Optimize multiple images in parallel

Fonts (rs.fonts):

Function	Description
`rs.fonts.download_google_font(family, options)`	Download Google Font files and generate local CSS (async)

JS Module (rs.js):

Function	Description
`rs.js.concat(paths, output, options?)`	Concatenate JS files with optional minification (async)
`rs.js.bundle(entry, output, options?)`	Bundle JS with imports via Rolldown (async)
`rs.js.bundle_many(entries, output_dir, options?)`	Bundle multiple JS entries to separate files (async)

CSS Module (rs.css):

Function	Description
`rs.css.concat(paths, output, options?)`	Concatenate CSS files with optional minification (async)
`rs.css.bundle(paths, output, options?)`	Bundle CSS with @import resolution via LightningCSS (async)
`rs.css.bundle_many(paths, output_dir, options?)`	Bundle multiple CSS entries to separate files (async)
`rs.css.purge(css_path, options?)`	Remove unused CSS based on HTML/JS output (async, call in after_build)
`rs.css.critical(html, css_path, options?)`	Extract critical CSS for a specific HTML page (async, returns string)
`rs.css.inline_critical(html_path, css_path, options?)`	Inline critical CSS into HTML with async loading for full CSS (async)

CSS options: minify (bool), purge (bool, default false), safelist (string[] regex patterns to always keep) Critical options: minify (bool), safelist (string[]), css_href (string, URL for async loading)

Asset Hashing (rs.assets):

Function	Description
`rs.assets.hash(content, length?)`	Compute SHA256 hash of content (async, returns handle)
`rs.assets.hash_sync(content, length?)`	Compute hash synchronously
`rs.assets.write_hashed(content, path, options?)`	Write file with content-hashed filename (async)
`rs.assets.register(original, hashed)`	Manually register original → hashed path mapping
`rs.assets.get_path(path)`	Get hashed path for original (or original if not found)
`rs.assets.manifest()`	Get table of all path mappings
`rs.assets.clear()`	Clear the manifest

PWA (rs.pwa):

Function	Description
`rs.pwa.manifest(options)`	Generate web app manifest.json (async)
`rs.pwa.service_worker(options)`	Generate service worker sw.js with caching strategies (async)

SEO (rs.seo):

Function	Description
`rs.seo.sitemap(options)`	Generate XML sitemap (async)
`rs.seo.robots(options)`	Generate robots.txt (async)

Tera Filter:

Use | asset in templates to resolve hashed asset paths:

<link rel="stylesheet" href="{{ '/styles/main.css' | asset }}">
<script src="{{ '/js/editor.js' | asset }}"></script>

Text Processing (rs.text):

Function	Description
`rs.text.slugify(text)`	Convert text to URL-friendly slug
`rs.text.word_count(text)`	Count words in text
`rs.text.reading_time(text, wpm?)`	Calculate reading time in minutes
`rs.text.truncate(text, len, suffix?)`	Truncate text with optional suffix
`rs.text.url_encode(str)`	URL encode a string
`rs.text.url_decode(str)`	URL decode a string

Path Utilities (rs.path):

Function	Description
`rs.path.join(...)`	Join path segments
`rs.path.basename(path)`	Get file name from path
`rs.path.dirname(path)`	Get directory from path
`rs.path.extension(path)`	Get file extension

Hash Functions (rs.hash):

Function	Description
`rs.hash.content(content)`	Hash content (xxHash64)
`rs.hash.file(path)`	Hash file contents

Collection Operations (rs.ops):

Function	Description
`rs.ops.filter(items, fn)`	Filter items where fn returns true
`rs.ops.sort(items, fn)`	Sort items using comparator
`rs.ops.map(items, fn)`	Transform each item
`rs.ops.find(items, fn)`	Find first item where fn returns true
`rs.ops.group_by(items, key_fn)`	Group items by key
`rs.ops.unique(items)`	Remove duplicates
`rs.ops.reverse(items)`	Reverse array order
`rs.ops.take(items, n)`	Take first n items
`rs.ops.skip(items, n)`	Skip first n items
`rs.ops.keys(table)`	Get all keys from a table
`rs.ops.values(table)`	Get all values from a table
`rs.ops.reduce(items, init, fn)`	Reduce items to single value

Parallel collection operations:

Function	Description
`rs.ops.par.map(items, fn, ctx?)`	Transform items in parallel (pass context explicitly)
`rs.ops.par.filter(items, fn, ctx?)`	Filter items in parallel (pass context explicitly)

Environment (rs.env):

Function	Description
`rs.env.get(name, default?)`	Get environment variable with optional default

Logging (rs.log):

Function	Description
`rs.log.trace(...)`	Log at trace level
`rs.log.debug(...)`	Log at debug level
`rs.log.info(...)`	Log at info level
`rs.log.warn(...)`	Log at warn level
`rs.log.error(...)`	Log at error level
`rs.log.print(...)`	Print to output

Git Information (rs.git):

Function	Description
`rs.git.info(path?)`	Get git info for repo or file (hash, branch, author, timestamp, dirty)
`rs.git.is_ignored(path)`	Check if path is gitignored

Note: All file operations respect the sandbox setting and are tracked for incremental builds. Paths can be relative (resolved from project root) or absolute.

Coroutine Helpers

Coroutine-based cooperative multitasking with a cleaner API:

local rs = require("rs-web")

-- Create and run tasks
local task1 = rs.coro.task(function()
  local data = rs.data.load_json("file1.json")
  rs.coro.yield()  -- cooperative yield
  return data
end)

-- Run single task to completion
local result = rs.coro.await(task1)

-- Run multiple tasks (interleaved execution)
local results = rs.coro.all({task1, task2, task3})

-- Race: return first completed
local winner, index = rs.coro.race({task1, task2})

Parallel Processing

True parallel execution using Rust's rayon thread pool. Each module has a .par submodule:

local rs = require("rs-web")

-- Load multiple JSON files in parallel (I/O parallelism)
local configs = rs.data.par.load_json({
  "content/problems/two-sum/config.json",
  "content/problems/reverse-string/config.json",
})

-- Load multiple YAML files in parallel
local data = rs.data.par.load_yaml({"a.yaml", "b.yaml", "c.yaml"})

-- Read multiple files in parallel
local contents = rs.fs.par.read({"a.txt", "b.txt", "c.txt"})

-- Parse frontmatter from multiple files in parallel
local posts = rs.data.par.load_frontmatter({
  "content/blog/post1.md",
  "content/blog/post2.md",
})
-- Returns: { { frontmatter = {...}, content = "...", raw = "..." }, ... }

-- Check multiple files exist in parallel
local exists = rs.fs.par.exists({"a.txt", "b.txt"})

-- Create directories in parallel
rs.fs.par.create_dirs({"dist/a", "dist/b", "dist/c"})

-- Copy files in parallel (sources, destinations)
rs.fs.par.copy(
  {"src/a.txt", "src/b.txt"},
  {"dist/a.txt", "dist/b.txt"}
)

-- Convert images in parallel
rs.image.par.convert(
  {"img/a.jpg", "img/b.jpg"},
  {"dist/a.webp", "dist/b.webp"},
  { quality = 85 }
)

-- TRUE PARALLEL map/filter (runs on rayon thread pool)
-- IMPORTANT: Upvalues are NOT captured. Pass context explicitly as 3rd argument.
local multiplier = 10
local doubled = rs.ops.par.map(items, function(x, ctx)
  return x * ctx.multiplier
end, { multiplier = multiplier })

local threshold = 5
local above = rs.ops.par.filter(items, function(x, ctx)
  return x > ctx.threshold
end, { threshold = threshold })

-- Simple functions without upvalues work directly
local squared = rs.ops.par.map(items, function(x) return x * x end)
local evens = rs.ops.par.filter(items, function(x) return x % 2 == 0 end)

-- Sequential operations (for non-serializable items)
local result = rs.ops.map(items, function(x) return x.name end)
local filtered = rs.ops.filter(items, function(x) return x.active end)

-- Reduce (sequential)
local sum = rs.ops.reduce(items, 0, function(acc, x) return acc + x end)

Async I/O (Tokio)

True async I/O backed by Tokio. All functions return handles - await with rs.async.await():

-- Spawn concurrent fetches
local t1 = rs.async.fetch("https://api.example.com/a", { cache = true })
local t2 = rs.async.fetch_bytes("https://fonts.example.com/font.woff2", { cache = true })
local t3 = rs.fonts.download_google_font("Lexend", { fonts_dir = "dist/fonts", css_path = "dist/fonts.css" })

-- Await all together
local results = rs.async.await_all({t1, t2, t3})

-- File operations (also return handles)
local write_task = rs.async.write_file("output.txt", "content")
local copy_task = rs.async.copy_file("src.txt", "dst.txt")
local dir_task = rs.async.create_dir("new/nested/dir")
rs.async.await_all({write_task, copy_task, dir_task})

-- Blocking fetch (returns response directly, no await needed)
local response = rs.async.fetch_sync("https://api.example.com/data")

Configuration Sections

Section	Key Settings
`site`	title, description, base_url, author (required)
`seo`	twitter_handle, default_og_image
`build`	output_dir
`paths`	templates

Frontmatter

Post frontmatter options (YAML or TOML):

---
title: "Post Title"           # Required
description: "Description"    # Optional
date: 2024-01-15              # Optional (YAML date or string)
tags: ["tag1", "tag2"]        # Optional
draft: false                  # Optional (default: false, excluded from build)
image: "/static/post.png"     # Optional: OG image
template: "custom.html"       # Optional: Override template
slug: "custom-slug"           # Optional: Override URL slug
permalink: "/custom/url/"     # Optional: Full URL override
encrypted: false              # Optional: Encrypt entire post
password: "post-secret"       # Optional: Post-specific password
---

Content Types

Markdown Files (.md)

Standard markdown files processed through the markdown pipeline.

HTML Files (.html)

HTML files with Tera templating support. Can use extends, includes, and all Tera features:

+++
title = "Custom Page"
date = 2024-01-15
+++
{% extends "base.html" %}

{% block content %}
<div class="custom">
  <h1>{{ page.data.post.title }}</h1>
  <p>By {{ site.author }}</p>
</div>
{% endblock %}

Partial Encryption

Markdown

Use :::encrypted blocks for partial content encryption:

Public content here.

:::encrypted
This content is encrypted with the global/post password.
:::

:::encrypted password="custom"
This block has its own password.
:::

HTML

Use <encrypted> tags in HTML files:

<p>Public content here.</p>

<encrypted>
  <p>This content is encrypted.</p>
</encrypted>

<encrypted password="custom">
  <p>This block has its own password.</p>
</encrypted>

Template Variables

Home Template (home.html)

site - Site config (title, description, base_url, author)
page - Page info (title, description, url, image)
sections - All sections with posts (sections.blog.posts)
content - Rendered markdown content

Post Template (post.html)

site - Site config
post - Post info (title, url, date, tags, reading_time, etc.)
page - Page info for head.html compatibility
content - Rendered markdown content
backlinks - Posts linking to this post (url, title, section)
graph - Local graph data (nodes, edges) for visualization

Graph Template (graph.html)

site - Site config
page - Page info
graph - Full graph data (nodes, edges)

License

MIT License. See LICENSE for details.

Name		Name	Last commit message	Last commit date
Latest commit History 78 Commits
.github/workflows		.github/workflows
src		src
tests		tests
.envrc		.envrc
.gitignore		.gitignore
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
flake.lock		flake.lock
flake.nix		flake.nix
rust-toolchain.toml		rust-toolchain.toml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

rs-web - Static Site Generator

Installation

Quick Start

Incremental Builds

Logging

Configuration

Lua Sandbox

Lua API Functions

Coroutine Helpers

Parallel Processing

Async I/O (Tokio)

Configuration Sections

Frontmatter

Content Types

Markdown Files (.md)

HTML Files (.html)

Partial Encryption

Markdown

HTML

Template Variables

Home Template (home.html)

Post Template (post.html)

Graph Template (graph.html)

License

About

Uh oh!

Releases 18

Packages

Languages

License

rslib/web

Folders and files

Latest commit

History

Repository files navigation

rs-web - Static Site Generator

Installation

Quick Start

Incremental Builds

Logging

Configuration

Lua Sandbox

Lua API Functions

Coroutine Helpers

Parallel Processing

Async I/O (Tokio)

Configuration Sections

Frontmatter

Content Types

Markdown Files (.md)

HTML Files (.html)

Partial Encryption

Markdown

HTML

Template Variables

Home Template (home.html)

Post Template (post.html)

Graph Template (graph.html)

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 18

Packages 0

Languages

Packages