gotic

gotic

Static-binary site generator that outputs a self-contained webserver executable.

Your content (templates, static assets, and Markdown posts) is embedded into a single Go binary. Run it anywhere — no runtime, no external files.

A complete, runnable site lives in example/ — cd example && go run . and open http://localhost:4321.

Fair warning

I'm building this for myself, so there's no guarantee of stability.

Getting started

Create project directory

$ mkdir mysite
$ cd mysite
$ mkdir static templates posts

// mysite.go
package main

import (
        "embed"

        "codeberg.org/filipsalo/gotic"
)

//go:embed static templates posts
var content embed.FS

func main() {
        gotic.Main(content)
}

Run server in dev mode with hot reload

$ go run mysite.go

When started with go run, gotic overlays the on-disk templates/, posts/, and static/ directories over the embedded content, so edits show up on the next refresh without rebuilding.

Build server binary

$ go build -o mysite mysite.go
$ ./mysite

On startup the server prints a clickable link, e.g.:

Listening on http://localhost:4321

Choose a port

The binary accepts a -port flag (default 4321):

$ ./mysite -port 8080

Posts

Posts are Markdown files in posts/, each beginning with a front-matter block between --- delimiters:

---
Title: Hello, world
Date: 2026-06-09
Tags: intro meta
Slug: hello-world
---

The **body** is Markdown and is rendered with the `markdown` template func.

Front-matter fields

Any other field is captured in .page.Meta (keyed by its lower-cased name), so you can add opt-in flags without code changes, e.g. a Notes: ... field is available as {{ .page.Meta.notes }}.

Pages

Pages are standalone Markdown files in pages/ (add pages to your //go:embed line to include them). Unlike posts they aren't dated and never appear in listings; each is served at /<slug> — the file or folder name, or an explicit Path/Slug — and rendered with page.html by default. They take the same front matter as posts.

Self-contained pages with colocated assets

A page can be a folder with an index.md instead of a single file. Its sibling files are then served as the page's own assets, under its URL:

pages/
  highlighter/
    index.md          → /highlighter
    playground.css    → /highlighter/playground.css
    playground.js     → /highlighter/playground.js

The page stays at /highlighter with no trailing slash; /highlighter/, the index.md source itself, and any ../ traversal are not served. A post can be a folder too (posts/2026-06-12-thing/index.md), with its assets under the post's dated URL.

Pair this with the Styles/Scripts front-matter fields to pull the assets into <head> without writing a bespoke template — a bare name resolves to the colocated file:

---
Title: Highlighter playground
Styles: playground.css
Scripts: playground.js
---

For default.html to honour them, emit them somewhere in <head>:

{{ range .page.Styles }}<link rel="stylesheet" href="{{ . }}">{{ end }}
{{ range .page.Scripts }}<script src="{{ . }}" defer></script>{{ end }}

Templates

Templates live in templates/. gotic ships default default.html (the page shell) and error.html; your site provides the page-specific templates it references — typically index.html (home), entry.html (a single post), page.html (a standalone page), and archive.html (the post index).

Rendering context

Each page is rendered with:

• .page — the current Page (.page.Title, .page.Body, .page.Date, .page.Tags, .page.Meta, …).
• .recent — the 15 most recent posts, newest first (for the home page).
• .posts — all posts, newest first (for the archive).

Synthetic pages

• / renders index.html.
• /archive renders archive.html — registered only when the site has at least one post, so a post-less single-page site doesn't get a broken archive route.

Template functions

Add your own with gotic.NewSite(content).WithTmplFuncs(funcs).

Serving multiple sites

Serve routes requests by Host header, so several independent sites can share one binary and port. gotic.Main(content) is shorthand for a single mount.

func main() {
        gotic.Serve(
                gotic.Mount{Domain: "infix.se", FS: infixContent, Dir: "infix.se"},
                gotic.Mount{Domain: "example.com", FS: exampleContent, Dir: "example.com"},
        )
}

Each Mount binds a domain to a content root. Hosts are normalized (port, trailing dot, and a leading www. are stripped), and every domain also answers on <label>.localhost for local development (so infix.se is reachable at http://infix.localhost:4321). The first mount is the fallback for unmatched hosts. Use Aliases to answer on additional hostnames.

Feeds

Set a Feed config on a mount to serve an Atom 1.0 feed at /feed.atom and a JSON Feed 1.1 at /feed.json. Both carry the full HTML of the most recent posts (drafts, unlisted, and future-dated posts are excluded, like every listing). A BaseURL is required — feeds need absolute URLs — and root-relative links in post bodies are rewritten to absolute ones so they resolve in readers.

func main() {
        gotic.Serve(gotic.Mount{
                FS:  content,
                Dir: ".",
                Feed: gotic.FeedConfig{
                        BaseURL:  "https://filipsalo.se",
                        Title:    "filipsalo.se",
                        Subtitle: "Filip Salo — software engineer",
                        Author:   "Filip Salo",
                },
        })
}

For multi-site Serve, BaseURL defaults to https://<Domain> when unset. Add autodiscovery links to your default.html <head> so readers find the feeds:

<link rel="alternate" type="application/atom+xml" href="/feed.atom" title="Atom feed">
<link rel="alternate" type="application/feed+json" href="/feed.json" title="JSON feed">