Extend the Go site generator

The sitegen package provides BuildWith for projects that need a small amount of project-specific content or rendering while retaining ZeroSite's Markdown publication, routing, link checks, navigation, search and safe output pipeline. Use the standard CLI when configuration is sufficient; use extensions for behavior that needs Go code.

Add a generated page and asset

An extension's Prepare hook receives the selected pages, parsed Markdown engine, repository path and mutable generated-asset map. It runs before final ordering, link resolution and output rendering. Context.AddHTMLPage registers trusted generated HTML under a logical source path, so the page participates in the standard navigation and routing rules.

package main

import (
	"log"

	"github.com/ornew/zerosite/sitegen"
)

func main() {
	c, err := sitegen.ReadConfig("site/config.json")
	if err != nil {
		log.Fatal(err)
	}
	c.Include = append(c.Include, "generated/**/*.md")
	extensions := sitegen.Extensions{
		Prepare: func(ctx *sitegen.Context) error {
			ctx.Assets["assets/build-info.json"] = []byte(`{"source":"local"}`)
			_, err := ctx.AddHTMLPage(
				"generated/status.md",
				"status/index.html",
				"Build status",
				[]byte(`<p>Generated by the site build.</p>`),
			)
			return err
		},
	}
	if _, err := sitegen.BuildWith(".", "site/dist", c, false, extensions); err != nil {
		log.Fatal(err)
	}
}

ReadConfig applies the standard defaults; DefaultConfig returns them without reading a file. BuildWith(repo, out, config, check, extensions) uses the same validation and staged output replacement as the command. Set check to true to validate without writing output. The generated page's source path is logical: it does not need to exist on disk, but it must be repository-relative and unique. The output path must be relative and collision-free. AddHTMLPage applies the configured include/exclude and publication rules; an excluded generated page returns no page and no error. Generated HTML is trusted and used verbatim: it is not sanitized, Markdown-processed, or checked for links embedded in raw HTML. Set Headings on a generated page when search should include heading entries; generated HTML does not infer headings automatically.

Extension hooks

sitegen.Extensions has narrowly scoped hooks:

• Prepare(*Context) error can inspect selected Context.Pages, add generated pages with AddHTMLPage, and add output-relative byte assets to Context.Assets.
• Decorate(*Context, *Page, string) (string, error) receives rendered page HTML and can add trusted project-specific markup before the layout wraps it.
• View(View) (any, error) can replace the data passed to the layout template.
• TemplateFuncs adds Go template functions to the layout's function map.
• Marker and MarkerContent customize the output ownership marker. Protected and AllowedOutput configure protected paths and permitted output paths for the shared publisher.
• Validate(stage string) error receives the temporary staged-output directory before publication, including in check mode. Use it to verify extension-produced files without changing the public output.

Context.Render(page) renders a parsed page using the configured Markdown engine. sitegen.HTMLText(html) extracts plain text from rendered HTML. Avoid using callbacks to reimplement ordinary publication or route handling; those remain controlled by the shared builder and Config.

Customize the layout

Config.Template replaces the full HTML layout, while Config.Templates loads additional named template files into the layout. An extension can also supply TemplateFuncs or return its own layout data through View. The standard view contains .Config, .Page, rendered .Body, navigation .Groups, .TOC, .Previous, .Next, output-relative asset URLs, .Source, .Canonical, .NoIndex, and .URL for constructing output-relative links. The default template is embedded from the selected ZeroSite version; paths to the Go module's files do not need to be present at runtime.

Keep custom behavior small

Configure generic behavior such as directory links, repository source links, search-index shape, TOC depth, templates, redirect rules and bundled assets in sitegen.Config. The full fields and defaults are in the configuration reference. Keep project-owned source pages and generated assets under that project's repository, and preserve the standard link, route and publication checks where possible.