PicoSSG - The Minimal Static Site Generator

PicoSSG is a minimal static site generator built on the philosophy of simplicity and predictability. It processes your markdown, nunjucks templates, and static files into a clean, static website with no configuration (unless you need it).

Guiding Principles

🚫 – Minimal Magic: Simple, predictable processing
0️⃣ – Zero Configuration: Works out of the box with sensible defaults
😎 – 1:1 File Mapping: Each source file maps directly to an output file
⚡️ – Tiny Feature Set: Only markdown, nunjucks and frontmatter processing, nothing more
🐾 – Small Footprint (and fast): Do only the work that is needed (7 files source code, 540 LOC)
📁 – Straightforward Processing: Markdown (.md), Nunjucks templates (.njk), or both combined
💪 – Flexibility When Needed: Optional hooks for pre- and postprocessing when you need more power

There is no plan to support more template engines.

How It Works

Make sure you have nodejs.org installed and then run on the command line:

npx @pic0/ssg -c content -o output

It will process all files in the content directory and put them into the output directory like so:

Files in `content`	Processing Steps	Files in `output`
`index.html.md`	Process as Markdown	`index.html`
`me/index.md`	Process as Markdown add `.html` extension	`me/index.html`
`css/style.css`	Copied as is	`css/style.css`
`image.webp`	Copied as is	`image.webp`
`blog/page.html.njk`	Process as Nunjucks	`blog/page.html`
`a/b/c/post.html.md.njk`	Process as Nunjucks then as Markdown	`a/b/c/post.html`
	... some (maybe) special cases ... 👇
`index.njk.njk`	Process nunjucks twice add `.html` extension	`index.html`
`style.njk`	Process nunjucks add `.html` extension	`style.html`
`image.njk`	Process nunjucks add `.html` extension	`image.html`

Key Features

Simple File Processing Rules

PicoSSG processes:

Markdown files (.md) using markdown-it
Nunjucks templates (.njk) using nunjucks
Combined files (.md.njk or .njk.md) - extensions processed from right to left
Static assets (copied as-is)
Files starting with underscore (_) are excluded from the output (_config.js, _layouts/ will not land in the output directory)
Optional front matter for metadata and layouts
Add .html extension automatically if needed (e.g. index.md becomes index.html)

Predictable Output

One of PicoSSG's most valuable features is its predictable 1:1 mapping from source to output:

content/about.html.md becomes output/about.html
content/about.md becomes output/about.html (.html extension added automatically)
content/index.md becomes output/index.html (.html extension added automatically)
content/posts/post.html.md.njk becomes output/posts/post.html
content/css/style.css is copied as is to output/css/style.css

⚠️ When processing file.md (as markdown), then removing the extension (which is PicoSSG's default behavior), it would result in a file without any extension, that is noticed and the extension .html is added automatically, so the output will be file.html.
Note that also happens for style.md or image.njk, etc. They will all become .html files!

`throwOnUndefined` Configuration

Out of the box PicoSSG is configured so that missing template variables halt execution, if you use {{ unknownVar }} in a nunjuck template the processing will fail.

Why? This is a best practice in order to prevent delivering code or content that "should do" but doesn't. Missing variables or misconfigured data are often a time eater, even worse when it only is noticed eventually once the content is already online for a while.

Getting Started

Ready to start using PicoSSG? Check out:

Examples

Looking for inspiration? Check out these sites built with PicoSSG:

PicoSPA - A prevent-SPA set of tools, to enhance MPAs without bloat (source code).
picostitch.com - Wolfram Kriesing's blog (source code)
JSCraftCamp.org site for 2025

Contribute

PicoSSG is open source and welcomes contributions. Check out the repository on Codeberg to contribute.