____ _ ____ ____ ____ | _ \(_) ___ ___/ ___/ ___| / ___| | |_) | |/ __/ _ \___ \___ \| | _ | __/| | (_| (_) |__) |__) | |_| | |_| |_|\___\___/____/____/ \____|

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 minimal configuration.

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 (2 files source code, 334 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

(Until now) 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 @wolframkriesing/picossg -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
style.css Copied as is style.css
image.webp Copied as is image.webp
page.html.njk Process as Nunjucks page.html
post.html.md.njk Process as Nunjucks, then as Markdown post.html

Key Features

Simple File Processing Rules

PicoSSG processes:

Predictable Output

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

Getting Started

Ready to start using PicoSSG? Check out:

Philosophy

PicoSSG is built on the belief that a static site generator should be:

  1. Simple to understand: The codebase should be small and easy to understand (334 LOCs)
  2. Predictable in operation: No magic, no surprises
  3. Minimal in configuration: Works out of the box
  4. Flexible when needed: Provides escape hatches for advanced use cases

This philosophy guides every decision in the development of PicoSSG.

Examples

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

Contribute

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