A simple, flexible, rule-based static site generator for Go developers.
S3Gen is a simple static site generator written in Go. It lets you do some frequent things very easily:
- Compile your posts and content written in markdown (.md) into html files to be served statically.
- Use Go templating and a rich set of "builtin" functions for you to use.
- Use custom templates for different pages in your website/blog.
- Generates an RSS feed so your site can be consumed via a feed reader
- Generates a sitemap useable by search engines
- Library mode to programatically serve static sites inside another binary
- Rule-based build system: Process files exactly how you want.
- Four-phase build pipeline: Discover → Transform → Generate → Finalize
- Powerful Go-based templating: with includes, custom functions, and more.
- Parametric Routes: Generate multiple pages from a single template (e.g., for tags or categories).
- Co-located Assets: Place images next to your markdown files.
- Transform Rules: SCSS, TypeScript, CSS minification, and more.
- Generators: Sitemap, RSS feed, and custom site-wide artifacts.
- Live Reloading for rapid development.
- Extensible: Add your own content types and build rules.
- Library-first: Use it as a standalone CLI or embed it in your own Go application.
go install github.com/panyam/s3gen@latest
TBD
This library is mainly for developers who are interested in hosting a blog but want control and customization easily. There are very few conventions needed for this.
A typical s3gen project has a content directory for the site's content, a templates directory for the Go templates, and a static directory for assets like CSS, JavaScript, and images. A main.go file configures the s3gen.Site object.
A minimal main.go showing how to configure and run a s3gen.Site:
package main
import (
"log"
"os"
s3 "github.com/panyam/s3gen"
)
var Site = s3.Site{
OutputDir: "./public",
ContentRoot: "./content",
PathPrefix: "/",
TemplateFolders: []string{
"./templates",
},
StaticFolders: []string{
"/static/", "static",
},
DefaultBaseTemplate: s3.BaseTemplate{
Name: "base.html",
},
// Co-located asset patterns
AssetPatterns: []string{
"*.png", "*.jpg", "*.jpeg", "*.gif", "*.svg",
},
}
// Generators for site-wide artifacts
var sitemapGen = &s3.SitemapGenerator{
BaseURL: "https://example.com",
OutputPath: "sitemap.xml",
}
var rssGen = &s3.RSSGenerator{
Title: "My Blog",
Description: "Latest posts",
BaseURL: "https://example.com",
OutputPath: "feed.xml",
}
func main() {
// Register generators
sitemapGen.Register(&Site)
rssGen.Register(&Site)
if os.Getenv("APP_ENV") != "production" {
log.Println("Starting watcher...")
Site.Watch()
select {}
} else {
Site.Rebuild(nil)
}
}A minimal content/index.html with some front matter:
---
title: "Home"
---
<h1>Welcome to my website!</h1>A minimal templates/base.html to render the content:
<!DOCTYPE html>
<html>
<head>
<title>{{.FrontMatter.title}}</title>
</head>
<body>
{{ BytesToString .Content | HTML }}
</body>
</html>To run the build:
go run main.goFor detailed documentation, see the /docs directory:
| Document | Description |
|---|---|
| 01-introduction.md | Philosophy and use cases |
| 02-core-concepts.md | Site, Resources, Rules, Build Process |
| 03-templating-guide.md | Template functions and syntax |
| 04-creating-content.md | Front matter, parametric pages, JSON data |
| 05-advanced-usage.md | Custom rules, programmatic use |
| 06-phase-based-architecture.md | The four-phase build pipeline |
| 07-co-located-assets.md | Images and files next to content |
| 08-transform-rules.md | CSS minification, SCSS, TypeScript |
| 09-generators-and-hooks.md | Sitemap, RSS, custom generators |
s3gen uses a four-phase build pipeline:
Discover → Transform → Generate → Finalize
│ │ │ │
│ │ │ └─ Sitemap, RSS, search index
│ │ └─ MD→HTML, HTML→HTML, parametric expansion
│ └─ SCSS→CSS, image optimization, bundling
└─ Find all resources, identify types, load metadata
Transform Phase:
CSSMinifier- Minify CSS filesExternalTransform- Run any command-line toolCopyRule- Copy static filesNewSCSSTransform()- SCSS compilationNewTypeScriptTransform()- TypeScript compilation
Generate Phase:
MDToHtml- Markdown to HTMLHTMLToHtml- HTML template processingParametricPages- Generate multiple pages from one template
Finalize Phase:
SitemapGenerator- Generate sitemap.xmlRSSGenerator- Generate RSS feed
Contributions are welcome! Please open an issue or submit a pull request.
This project is licensed under the MIT License.