taragen

package module
v0.0.0-...-6eab845 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 20, 2026 License: MIT Imports: 38 Imported by: 0

README

taragen

Fast, minimal static site generator.

Taragen turns a folder of JSX, Markdown, and Go template files into a static website. It ships as a single binary with a JavaScript engine built in, so there is no Node.js, no npm install, and no config file: the file tree is the configuration.

brew tap progrium/homebrew-taps
brew install taragen

mkdir mysite && cd mysite
echo '<h1>Hello World</h1>' > index.jsx
taragen serve     # preview at http://localhost:8088 with live reload
taragen build     # write the site to _public/

Read the manual for a full guide to building sites, with tutorials for blogs, tag pages, docs sections, share cards, and more.

Features

Pages and templates

  • JSX pages, layouts, and partials, rendered to HTML on the server with no client runtime. Text and attributes are escaped by default, with raw() for trusted HTML.
  • Markdown pages with YAML frontmatter, and Go templates ([[ ]] delimiters).
  • Layouts that nest by folder, and an explicit layout key to choose or turn them off.
  • Global JS helpers (_globals.jsx) and default page data (_defaults.jsx), scoped to their folder and below.
  • Any text format as a page: RSS feeds, sitemaps, JSON, with their own content type.

Content and navigation

  • pages() listings by path, wildcard, or recursive ** pattern, filtered by page data with where, in a stable order on every build.
  • Generated pages from bracketed file names, such as tags/[tag].jsx or logs/[year]/[month].jsx, for tag pages and archives.
  • Backlinks: every page knows which pages link to it, from links in page bodies.
  • Drafts, by flag or future date, visible in serve and left out of build.

Outputs

  • Extra outputs per page from _outputs/ templates, like a .txt version beside every page, listed in page.outputs for layouts and feeds.
  • PNG share cards rendered from SVG templates with your site's own fonts, plus measureText() for fitting titles. No headless browser.
  • Aliases for moved pages and a Netlify-style _redirects file, written as redirect pages that work on any static host and served as real redirects in development.
  • Syntax highlighting with Chroma CSS classes, styled by your stylesheet.

Workflow

  • taragen serve renders on request, shows drafts, and live reloads on any change, including CSS.
  • taragen build cleans _public/ (keeping a .git deploy checkout), and produces byte-identical output for the same sources, so diffs are reviewable.
  • URL collisions between pages, outputs, aliases, and files are build errors, never silent overwrites.
  • One binary for macOS, Linux, and Windows on amd64 and arm64.

A taste

A site:

mysite/
├── _assets/style.css
├── _defaults.jsx          siteURL = "https://example.com"
├── _globals.jsx           siteTitle = "My site"
├── _layout.jsx
├── _outputs/
│   └── card.png.jsx       one share card per page
├── index.jsx
├── articles/
│   ├── index.jsx
│   ├── feed.xml.jsx
│   └── 2021/ngrok.md
└── tags/[tag].jsx         one page per tag

A layout, using backlinks and the share card output:

// _layout.jsx
(content) =>
<html>
  <head>
    <title>{page.title} · {siteTitle}</title>
    <link rel="stylesheet" href="/_assets/style.css" />
    {page.outputs?.card && <meta property="og:image" content={`${page.siteURL}${page.outputs.card}`} />}
  </head>
  <body>
    <main>{content}</main>
    {page.backlinks.length > 0 && <aside>
      <h2>Linked from</h2>
      <ul>{page.backlinks.map(p => <li><a href={p.path}>{p.title}</a></li>)}</ul>
    </aside>}
  </body>
</html>

A page per tag:

// tags/[tag].jsx
params(() => [...new Set(pages("**").flatMap(p => p.tags ?? []))].map(tag => ({ tag })));
data({ title: `Tagged ${page.params.tag}` });
<ul>
  {pages({ where: { tags: page.params.tag } }).reverse().map(p =>
    <li><a href={p.path}>{p.title}</a></li>
  )}
</ul>

The manual covers each of these in detail.

Install

  • Homebrew: brew tap progrium/homebrew-taps && brew install taragen
  • Binary: download a release for your platform from GitHub releases.
  • From source: with Go installed, make build writes .local/bin/taragen, and make link symlinks it into /usr/local/bin.

Documentation

  • MANUAL.md: the user guide for building sites.
  • design/SPEC.md: how taragen works inside, for contributors.
  • design/: design proposals and the process for changing taragen.
  • web/: the taragen website, which is also an example site.

Development

Command What it does
make build Build .local/bin/taragen with the version from git.
make test Run go test ./....
make dist Cross-compile for darwin, linux, and windows on amd64 and arm64 into .local/dist/.
make web-serve / make web-build Serve or build the example site in web/.
make design-check Check the design proposals.

Building needs only Go. The share card rasterizer is resvg compiled to WebAssembly and embedded in the binary; only changing that module needs Rust (see its Makefile target).

Changes to taragen's behavior go through a design proposal first; see the design process. Agents working in the repository follow AGENTS.md.

License

MIT

Documentation

Index

Constants

View Source
const (
	ExtMarkdown = ".md"
	ExtTemplate = ".tmpl"
	ExtJSX      = ".jsx"
)
View Source
const (
	// Links is the page data key for the pages a page's body links to.
	Links = "links"
	// Backlinks is the page data key for the pages that link to a page.
	Backlinks = "backlinks"
	// SiteURL is the page data key for the site's absolute origin, such as
	// "https://example.com", used to recognize absolute links to the site.
	SiteURL = "siteURL"
)
View Source
const (
	Layout      = "layout"
	Slug        = "slug"
	Path        = "path"
	Source      = "src"
	Body        = "body"
	IsDir       = "isDir"
	Date        = "date"
	ContentType = "contentType"
	Draft       = "draft"
	Preamble    = "preamble"
	Outputs     = "outputs"
)
View Source
const Aliases = "aliases"

Aliases is the page data key listing old URL paths that redirect to the page.

View Source
const AssetsDir = "_assets"

AssetsDir is the root-level directory copied verbatim by build.

View Source
const OutputsDir = "_outputs"

OutputsDir is the directory that holds output templates, in any directory of the site.

View Source
const Params = "params"

Params is the page data key holding a generated page's parameter set.

View Source
const RedirectsFile = "_redirects"

RedirectsFile is the root file listing redirects, in a subset of Netlify's _redirects format.

Variables

Functions

func ExportJSX

func ExportJSX(name string, src []byte, globals map[string]any) (map[string]any, error)

func RenderJSX

func RenderJSX(name string, src []byte, globals map[string]any, args ...any) ([]byte, error)

func RenderTemplate

func RenderTemplate(name string, src []byte, funcs template.FuncMap) ([]byte, error)

Types

type Data

type Data map[string]any

func SplitFrontmatter

func SplitFrontmatter(src []byte) (Data, []byte, error)

type JSXParser

type JSXParser struct{}

func (*JSXParser) Parse

func (f *JSXParser) Parse(p *Page) (out []byte, data Data, err error)

type MarkdownParser

type MarkdownParser struct{}

func (*MarkdownParser) Parse

func (f *MarkdownParser) Parse(p *Page) ([]byte, Data, error)

type Output

type Output struct {
	// Name is the output's name, such as "card" for _outputs/card.png.jsx.
	Name string
	// Suffix is appended to the page's URL, such as ".card.png".
	Suffix string
	// Template is the template's path relative to the site root.
	Template string
	// Page is the page the output belongs to.
	Page *Page
}

Output is an extra file written for a page by an _outputs template.

func (*Output) Render

func (o *Output) Render(w io.Writer) (contentType string, err error)

Render re-parses the output's page and renders the output to w. It returns the output's content type.

func (*Output) URL

func (o *Output) URL() string

URL returns the output's URL: the page's URL with the suffix appended, with "index" standing in for the root page.

type Page

type Page struct {
	// contains filtered or unexported fields
}

func (*Page) Aliases

func (p *Page) Aliases() []string

Aliases returns the page's normalized aliases, as of its last parse.

func (*Page) Body

func (p *Page) Body() []byte

func (*Page) ContentType

func (p *Page) ContentType() string

func (*Page) Date

func (p *Page) Date() string

func (*Page) Draft

func (p *Page) Draft() bool

func (*Page) IsDir

func (p *Page) IsDir() bool

func (*Page) Outputs

func (p *Page) Outputs() []*Output

Outputs returns the page's outputs that apply to it and are turned on, as of its last parse.

func (*Page) Parse

func (p *Page) Parse() error

func (*Page) Preamble

func (p *Page) Preamble() string

func (*Page) Render

func (p *Page) Render(w io.Writer) (err error)

func (*Page) Slug

func (p *Page) Slug() string

func (*Page) Source

func (p *Page) Source() []byte

func (*Page) Subpages

func (p *Page) Subpages() (subpages []*Page)

func (*Page) Template

func (p *Page) Template() string

Template returns the template source a generated page renders from, relative to the site root, or "" for any other page.

func (*Page) Time

func (p *Page) Time() time.Time

func (*Page) URL

func (p *Page) URL() string

URL returns the page's URL path, such as "/" or "/docs/intro".

type PageParser

type PageParser interface {
	Parse(p *Page) ([]byte, Data, error)
}

type RedirectRule

type RedirectRule struct {
	// Line is the rule's line number in _redirects, from 1.
	Line int
	// From is the normalized source path. For a wildcard rule it is the path
	// the wildcard is below, without "/*".
	From string
	// Wildcard is true when the rule's from ended in "/*".
	Wildcard bool
	// To is the target as written: a path, possibly with a query string, or
	// an absolute http or https URL, possibly containing :splat.
	To string
	// Status is the redirect's HTTP status.
	Status int
}

RedirectRule is one rule from the _redirects file.

func (*RedirectRule) String

func (r *RedirectRule) String() string

type Route

type Route struct {
	Kind RouteKind
	// URL is the path the route is served at, such as "/", "/about",
	// "/about.txt", or "/img/logo.svg".
	URL string
	// File is where build writes the route, relative to the output
	// directory, such as "index.html" or "about/index.html".
	File string
	// Page is the page for page, output, and alias routes. For a redirect
	// route it is the page a stub or copy is written for, if any.
	Page *Page
	// Output is the output for output routes.
	Output *Output
	// Source is the absolute source filename for static routes.
	Source string
	// Target is where an alias or redirect route points.
	Target string
	// Rule is the _redirects rule for redirect routes.
	Rule *RedirectRule
}

Route is one URL the site serves and what produces it.

func (*Route) Draft

func (r *Route) Draft() bool

Draft reports whether the route is a draft: a draft page or an output of one. build skips drafts and serve serves them.

func (*Route) String

func (r *Route) String() string

String describes the route's producer, for error messages.

type RouteKind

type RouteKind string

RouteKind says what produces a route's URL.

const (
	// RoutePage is a page with a source file, or a page generated from a
	// template.
	RoutePage RouteKind = "page"
	// RouteOutput is an output of a page, from an _outputs template.
	RouteOutput RouteKind = "output"
	// RouteStatic is a file copied verbatim.
	RouteStatic RouteKind = "static"
	// RouteAlias is an old URL of a page, from its aliases.
	RouteAlias RouteKind = "alias"
	// RouteRedirect is a redirect from the _redirects file.
	RouteRedirect RouteKind = "redirect"
)

type RouteTable

type RouteTable struct {
	// contains filtered or unexported fields
}

RouteTable maps every URL the site serves to what produces it. Each URL, and each output file, has exactly one producer.

func NewRouteTable

func NewRouteTable() *RouteTable

func (*RouteTable) Add

func (t *RouteTable) Add(r *Route) error

Add adds a route. A route whose URL or output file is already taken is an error naming both producers.

func (*RouteTable) Lookup

func (t *RouteTable) Lookup(urlPath string) *Route

Lookup returns the route for a request path, ignoring leading and trailing slashes, or nil.

func (*RouteTable) Routes

func (t *RouteTable) Routes() []*Route

Routes returns every route, ordered by output file.

type Site

type Site struct {
	// contains filtered or unexported fields
}

func NewSite

func NewSite(dir string, drafts bool) *Site

func (*Site) Fonts

func (s *Site) Fonts() (*raster.Fonts, error)

Fonts returns the site's font database, loading it on first use.

func (*Site) GenerateAll

func (s *Site) GenerateAll(dest string, clobber bool) (err error)

func (*Site) IsPage

func (s *Site) IsPage(path string) bool

func (*Site) Page

func (s *Site) Page(normalPath string) *Page

func (*Site) Pages

func (s *Site) Pages(query string) ([]*Page, error)

Pages returns the listing for a path or pattern, as pages(query) in JSX.

func (*Site) ParseAll

func (s *Site) ParseAll() error

ParseAll resets the page map, parses every page found by walk, generates the pages for every template from the real pages, builds the route table, and builds the link graph.

func (*Site) Partial

func (s *Site) Partial(name string, globals map[string]any, args ...any) ([]byte, error)

func (*Site) Query

func (s *Site) Query(paths []string, where map[string]any) ([]*Page, error)

Query returns the union of the listings for each path or pattern, once each, keeping only pages whose data matches every key in where, sorted as one listing.

func (*Site) Routes

func (s *Site) Routes() *RouteTable

Routes returns the route table built by the last ParseAll.

func (*Site) ServeHTTP

func (s *Site) ServeHTTP(w http.ResponseWriter, r *http.Request)

func (*Site) WatchForReloads

func (s *Site) WatchForReloads()

type TemplateParser

type TemplateParser struct{}

func (*TemplateParser) Parse

func (f *TemplateParser) Parse(p *Page) ([]byte, Data, error)

Directories

Path Synopsis
cmd
taragen command
internal
design
Package design implements the proposal-driven design workflow described in design/README.md: parsing proposal frontmatter, validating proposals, and computing their state from git.
Package design implements the proposal-driven design workflow described in design/README.md: parsing proposal frontmatter, validating proposals, and computing their state from git.
raster
Package raster turns SVG into PNG with resvg, compiled to WebAssembly and run by wazero, so taragen stays a pure-Go binary.
Package raster turns SVG into PNG with resvg, compiled to WebAssembly and run by wazero, so taragen stays a pure-Go binary.
tools
design command
Command design runs taragen's proposal-driven design workflow.
Command design runs taragen's proposal-driven design workflow.
docs command
Command docs splits MANUAL.md into the website's docs pages.
Command docs splits MANUAL.md into the website's docs pages.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL