fuego

README

Fuego

A meta-engine for static site generation in Go. Define custom DSLs (.trivia, .card, .pitch, anything), map them to HTML through a configurable parsing and rendering pipeline, and build static sites from arbitrary content formats.

Documentation

Why Fuego?

Most SSGs are Markdown-first. Fuego is format-agnostic. You define the content format, the parsing rules, and the templates. Fuego handles discovery, routing, taxonomy indexing, collections, and the build pipeline. No format is privileged — Markdown is a first-party parser you opt into (eng.Register(markdown.Parser())), the same as any other. The real power is custom formats, packaged and shared as format packs.

Install

go install github.com/gofuego/fuego/cmd/fuego@latest

Requires Go 1.25+. Adds fuego to $GOPATH/bin (usually ~/go/bin).

Quick Start

fuego init mysite
cd mysite
fuego build

This scaffolds a working project with a .card flashcard DSL, a paginated collection, a Markdown homepage, a partial-driven nav, RSS/sitemap outputs, and a dev server:

mysite/
  CLAUDE.md          # agent-friendly project guide
  config.yaml        # site config, parsers, collections
  main.go            # engine entry point — registers the Markdown parser
  content/
    index.md         # Markdown homepage
    cards/           # sample .card DSL collection (paginated)
  theme/
    base.html        # HTML shell
    layouts/         # named layout overrides (home, card, listing)
    partials/        # nav.html, driven by .Site.Pages
    renderers/       # per-node-type rendering (front, back, page-ref)
    outputs/         # sitemap.xml + rss.xml (non-HTML outputs)
  public/
    style.css        # starter stylesheet

fuego serve          # dev server at http://localhost:8080

Key Features

• Format-agnostic — define content formats via config (declarative regex parsers) or Go code (compiled parsers)
• Markdown — opt-in GFM support via goldmark (tables, strikethrough, autolinks, task lists)
• Format packs — bundle parsers, hooks, and themes into installable modules via eng.Use(), with namespaced config and deep-merged defaults
• Three-tier routing — frontmatter slug > config pattern > filesystem mirror
• Taxonomies & collections — automatic term pages, index pages, and sorted listing pages, with optional pagination
• Cross-page templates — .Site.Pages, partials, and query funcs (where, sortBy, …) for navs and listings
• Non-HTML outputs — RSS, sitemaps, and search indexes from theme/outputs/
• Hooks — AfterParse, Index, and BeforeRender Go functions to enrich, filter, or transform pages
• Incremental builds — opt-in parse cache + render narrowing, byte-identical to a clean build
• Broken-link checking — opt-in (--check-links / --strict-links) <base href>-aware validation of internal links, reported against the source file
• Embeddable — a programmatic API (engine.Build/Serve/Validate) for building domain-specific generators on top of Fuego
• Dev server — file watching, live rebuild, optional Vite proxy
• Site manifest — site-manifest.json with a page index (each page's source and output paths), taxonomy terms, and collection membership
• Deterministic output — sorted keys, reproducible builds

Example: Custom Parser in Config

parsers:
  trivia:
    rules:
      - match: '^\?\s*(.+)$'
        emit:
          type: question
          content: "$1"
      - match: '^\[([A-Z])\]\s+(.+)$'
        emit:
          type: answer
          content: "$2"
          attributes:
            letter: "$1"

This lets you write .trivia files and have them parsed into a universal AST that your templates render however you want.

CLI

fuego build      Build the static site
fuego serve      Dev server with live rebuild
fuego validate   Check for structural errors without rendering (for CI)
fuego list       Print all pages as TYPE | SOURCE | URL
fuego config     Print the resolved config with per-key provenance
fuego init       Scaffold a new project
fuego --version  Print the version

Key build / serve flags:

--base-url <path>   override site base_url for one run (deploy subpath, e.g. /owner/repo)
--incremental       reuse the parse cache for unchanged content (build)
--check-links       report internal links that don't resolve (run with --base-url)
--strict-links      fail the build on a broken internal link (implies --check-links)
--config <path>     config file (default config.yaml)
fuego init --pack M scaffold wired to a format pack

Documentation

The docs site lives in its own repo — gofuego/fuego-docs — itself a Fuego project (dogfooding), built against the published engine and hosted + edited in place via fuego-studio. It covers getting started, configuration, custom parsers, templates, hooks, format packs, embedding, and the CLI reference.

License

MIT

Documentation

Overview

Package fuego is a meta-engine for static site generation. See github.com/gofuego/fuego/engine for the public API.