templsite

README

templsite

A static site generator built with Go and templ components. Zero Node.js dependencies, type-safe templates, modern CSS with Tailwind v4.

At a Glance

• templsite CLI scaffolds new sites (templsite new).
• Your site binary (./site) owns rendering using your components.
• templsite library (pkg/*) provides parsing, assets, and dev server primitives.

Is this for me?

Great fit if you want:

• Compile-time template safety with Go + templ
• No Node.js dependency chain for the core pipeline
• Full ownership of components and rendering logic

Probably not ideal if you want:

• A single precompiled universal SSG binary with runtime theme/template loading
• A no-Go workflow where templates are edited without compiling

Why templsite?

• Type-safe templates — templ components are Go functions, not string templates. Errors are caught at compile time.
• Zero Node.js — Pure Go toolchain. Tailwind CSS v4 runs via standalone CLI.
• Full customization — Each site compiles its own binary with its own components. No theme layer to fight with.

See ARCHITECTURE.md for the design rationale.

60-Second Install & Run

# Install the CLI
go install github.com/dmoose/templsite/cmd/templsite@latest

# Scaffold and run a new site
templsite new mysite --template tailwind
cd mysite
make serve

If you are testing unreleased changes, use @main instead of @latest.

Quick Start

# Install
git clone https://github.com/dmoose/templsite
cd templsite
make setup && make build

# Create a site
templsite new mysite --template tailwind
cd mysite
make serve

Your site is running at http://localhost:8080 with live reload.

How It Works

Each site is a standalone Go project. The templsite library provides content parsing, asset building, and a dev server. Your site's main.go controls rendering using your own templ components.

mysite/
├── main.go              # Your binary — renders with YOUR components
├── components/          # templ components (customize these)
│   ├── layout/
│   │   ├── base.templ   # HTML shell
│   │   └── page.templ   # Page layout
│   └── ui/
│       ├── header.templ
│       └── footer.templ
├── content/             # Markdown with YAML frontmatter
├── assets/css/app.css   # Tailwind CSS v4 entry point
├── config.yaml          # Site configuration
└── public/              # Generated output (gitignored)

Features

• Live reload — WebSocket-based auto-refresh during development
• Content organization — Sections, taxonomies (tags/categories), prev/next navigation
• Feeds and SEO — RSS, Atom, JSON Feed, sitemap.xml, robots.txt
• Pagination — Built-in paginator with URL generation
• Page enrichment — Summary, reading time, word count, table of contents
• Data files — Load YAML/JSON data for use in templates
• Navigation menus — Configurable menus with active state tracking
• Environment configs — --env flag with config overlay files
• Content scaffolding — Archetypes for ./site new posts/my-post
• Syntax highlighting — Code blocks highlighted with Chroma
• LLMs.txt — Auto-generated llms.txt with companion markdown files for LLM consumption

Commands

# templsite CLI
templsite new <path>                             # Create site (tailwind template)
templsite new <path> --template tailwind         # Explicit template selection
templsite new <path> --templsite-path ../templsite  # Local dev mode

# Site commands (in your site directory)
make serve        # Dev server with live reload
make build        # Compile site binary
make deploy       # Generate static files to public/
make prod         # Production build (uses config.production.yaml)

Configuration

title: "My Site"
baseURL: "https://example.com"
description: "Site description for feeds"
language: "en"

taxonomies:
  - tags
  - categories

menus:
  main:
    - name: Home
      url: /
      weight: 1
    - name: About
      url: /about/
      weight: 2

build:
  drafts: false
  future: false

llms:
  enabled: true

For environment overrides, create config.production.yaml with only the fields that change.

Content

Markdown files in content/ with YAML frontmatter:

---
title: "My Blog Post"
date: 2025-01-15
draft: false
tags: ["golang", "web"]
---

Your content here with **Markdown** formatting.

<!--more-->

Content after this marker is excluded from the summary.

URL structure

File path	URL
content/index.md	/
content/about.md	/about/
content/blog/_index.md	/blog/
content/blog/first-post.md	/blog/first-post/

Customizing Components

Edit any .templ file in components/. Changes are compiled and reloaded automatically during make serve.

// components/ui/header.templ
package ui

templ Header(title string) {
    <header class="bg-white shadow">
        <div class="max-w-7xl mx-auto px-4 py-6">
            <a class="text-xl font-bold" href="/">{title}</a>
        </div>
    </header>
}

Deployment

make deploy    # Generates public/ directory

Upload public/ to any static host — Netlify, Vercel, GitHub Pages, S3 + CloudFront, etc.

Documentation

• Guide: Templ Developer — Full guide: content features, pagination, taxonomies, feeds, deployment
• Architecture — Why each site compiles its own binary

FAQ

Why does each site compile its own binary? Templ components are Go functions compiled at build time, not runtime templates. Each site must be a Go project to allow component customization with type safety and IDE support. See ARCHITECTURE.md.

Do I need to know Go? Basic Go helps, but you can get started by editing Markdown content, customizing templ components (HTML-like syntax), and using Tailwind utility classes. The Makefile handles most complexity.

Requirements

• Go 1.26+
• templ CLI

License

MIT License — see LICENSE for details.

Copyright (c) 2025-2026 Catapulsion LLC and contributors