Whiskey

A dependency-aware static site generator written in Go

View on GitHub Live Site

Whiskey

A dependency-aware static site generator written in Go.

Documentation Go Version License: MIT

whiskey is a modern static site generator built around dependency-aware incremental builds.

Instead of rebuilding your entire site whenever something changes, whiskey constructs a dependency graph connecting content, layouts, partials, assets, and remote sources. When a change occurs, only the pages affected by that change are rebuilt.

Unlike traditional static site generators that fetch remote content during rendering, whiskey synchronizes external sources into a persistent workspace before rendering begins. This enables deterministic builds, offline support, conditional HTTP caching, and reproducible outputs.

Why whiskey?

Most static site generators think in terms of files.

Whiskey thinks in terms of dependencies.

Markdown
     │
     ▼
Dependency Graph
     │
     ▼
Dirty Set
     │
     ▼
Incremental Build

Instead of rebuilding the world, Whiskey asks:

"Which pages actually depend on what changed?"

That philosophy drives every part of the architecture.

Commands

Usage:
  whiskey [command]

Available Commands:
  build       Build the site
  check       Inspect site dependencies
  clean       Clean generated artifacts
  help        Help about any command
  serve       Build and serve a Whiskey site
  sync        Synchronize remote sources
  theme       Manage local themes
  version     Version information about whiskey

Flags:
  -h, --help   help for whiskey

Use "whiskey [command] --help" for more information about a command.

Features

Build System

  • Dependency-aware incremental builds
  • Graph-driven dirty propagation
  • SHA256 fingerprinting
  • Configuration-aware rebuilds
  • Pretty URLs
  • Incremental asset pipeline
  • Live reload development server

Content

  • Markdown + YAML frontmatter
  • Draft support
  • Multi-page sites
  • Collections
  • Tags
  • RSS feeds
  • Sitemap generation
  • Image shortcodes
  • YouTube embeds

Templates

  • Layout inheritance
  • Base templates
  • Partials
  • Theme fallback
  • Four bundled themes (minimal, paper, terminal, noir)

Remote Content

  • Remote Markdown includes
  • Local includes
  • Persistent materialized workspace
  • Offline builds
  • Conditional HTTP caching
  • Workspace garbage collection
  • HTML → Markdown extraction

Developer Experience

  • Live reload
  • Recursive file watching
  • Automatic rebuilds
  • Browser refresh
  • Dependency graph visualization
  • Remote synchronization

Architecture

Whiskey separates source synchronization from page rendering.

                Markdown
                   │
                   ▼
           Dependency Graph
                   │
                   ▼
          Dirty Set Calculation
                   │
                   ▼
         Source Materialization
                   │
                   ▼
          .whiskey/workspace/
                   │
                   ▼
           Template Rendering
                   │
                   ▼
                 dist/

Because rendering consumes only workspace artifacts, builds become deterministic and independent of network availability.

Key Architectural Components

The codebase is organized into highly modular packages under the internal/ directory:

  1. Parser (internal/parser): Extracts YAML frontmatter metadata, expands template shortcodes (such as image and youtube), and compiles Markdown content into HTML.
  2. Dependency Graph (internal/graph): A Directed Acyclic Graph (DAG) representing layouts, partial templates, assets, pages, and includes as nodes. Edges represent dependencies (e.g. PageNode -> LayoutNode).
  3. Workspace & Materialization (internal/source): Manages the cached HTTP local workspace under .whiskey/workspace/. It implements conditional HTTP caching (verifying ETags and Last-Modified timestamps in .whiskey/manifest.json before performing downloads).
  4. Fingerprint Store (internal/fingerprint): Tracks cryptographic SHA-256 hashes of all inputs in .whiskey/fingerprints.json to detect file updates.
  5. Incremental Planner (internal/planner): Decides if a layout or configuration change demands a full build, otherwise calculates the minimal set of dirty pages by analyzing the reverse path of changed inputs.
  6. HTML Renderer (internal/template): Loads theme HTML layouts and compiles output pages. Handles local and remote include expansion recursively.

Frontmatter

Every content Markdown file defines metadata using YAML frontmatter. The default fields are:

title: "My Page Title"
description: "A description of the page content"
date: 2026-07-13
layout: "page"
draft: false
tags:
  - general
  • title: The display name of the page, injected into headers and <title> tags.
  • description: A summary of the page, injected into HTML meta tags.
  • date: Publication date used for sorting collections.
  • layout: The template design used (e.g. page, post, index).
  • draft: If true, the page is tracked for changes but is not rendered in publishing mode (and is hidden from collections, navigation, feeds, and sitemaps).
  • unlisted (or hidden): If true, the page is rendered to HTML so it can be accessed directly by URL, but is omitted from auto-generated navigation menus, RSS feeds, sitemap XML, and collection/tag lists (perfect for custom 404 pages or secret easter egg pages!).
  • tags: Lists taxonomies for grouping and tag lists.

Custom 404 & Unlisted Pages

  • Custom 404 Page: Create content/404.md to define a custom error page. It is compiled into dist/404.html (and dist/404/index.html), automatically excluded from navigation, RSS feeds, and sitemaps, and served by whiskey serve whenever a missing route is requested.
  • Easter Eggs & Unlisted Pages: Add unlisted: true (or hidden: true) to frontmatter for any page you want published at a direct URL without appearing in auto-generated UI lists or navigation.

Installation

Requirements

  • Go 1.25+

Clone the repository:

git clone https://github.com/sxijyoti/whiskey.git
cd whiskey

To run:

# Build:
make build

# Install:
make install

or simply,

make whiskey 
# this handles build and install

Verify:

whiskey version

Quick Start

Create a new site:

site/
├── whiskey.toml
├── content/
├── layouts/
├── static/
└── themes/

# Build:
whiskey build

# Serve:
whiskey serve

# Synchronize remote sources:
whiskey sync

# Offline build:
whiskey build --offline

Project Structure

site/
├── whiskey.toml
├── content/
├── layouts/
├── static/
├── themes/
│
├── dist/
│
└── .whiskey/
    ├── fingerprints.json
    ├── manifest.json
    └── workspace/

Dependency Graph

Everything inside Whiskey is represented as graph nodes.

Current node types include:

  • Pages
  • Layouts
  • Partials
  • Assets
  • Remote Sources

Example:

Page
 │
 ▼
Layout
 │
 ▼
Base
 │
 ▼
Partials

and

Page
 │
 ▼
Remote Source

Whenever a node changes, Whiskey traverses the graph to determine which pages become dirty.

Incremental Builds

Every build input is fingerprinted.

Tracked inputs include:

  • Markdown
  • Layouts
  • Partials
  • Assets
  • Configuration
  • Remote Sources

Build flow:

Changed Node
      │
      ▼
Dependency Graph
      │
      ▼
Affected Pages
      │
      ▼
Incremental Build

Only affected pages are rebuilt.

Remote Includes

Include external Markdown directly inside your content.

@include https://raw.githubusercontent.com/sxijyoti/whiskey/main/README.md

Pipeline:

Remote URL
      │
      ▼
Provider
      │
      ▼
Materialization
      │
      ▼
Workspace
      │
      ▼
Rendering

Workspace-backed Sources

Remote content is synchronized before rendering.

Source Provider
        │
        ▼
Fetch
        │
        ▼
Workspace
        │
        ▼
Page Rendering

Pages never perform network requests directly.

This enables:

  • deterministic builds
  • reproducible outputs
  • offline builds
  • reusable cached content

Conditional HTTP Requests

Whiskey minimizes unnecessary downloads through HTTP cache validation.

Metadata
     │
     ▼
Conditional Request
     │
     ├── 304 Not Modified
     │         │
     │         ▼
     │   Reuse Workspace
     │
     └── 200 OK
               │
               ▼
        Update Workspace

Supported headers:

  • ETag
  • Last-Modified

HTML Extraction

HTML sources are automatically normalized into Markdown.

HTTP
   │
   ▼
Content-Type
   │
   ├── text/html
   │
   ▼
Defuddle
   │
   ▼
Markdown
   │
   ▼
Workspace

This keeps the rendering pipeline content-format agnostic.

Offline Builds

Synchronize once:

whiskey sync

Then build anywhere.

whiskey build --offline

Remote sources are served entirely from the workspace.

Themes

Whiskey ships with four bundled themes.

  • minimal — Clean and minimal
  • terminal — Hacker-inspired terminal aesthetic
  • paper — Traditional document style
  • noir — Dark editorial layout

Themes consist of:

  • layouts
  • partials
  • static assets