README
¶
Foundry Core
Foundry Core is a small Go library of stable primitives for generating static sites. It focuses on fast full rebuilds, parallel generation, diff-aware file writes, translation helpers, and template ergonomics while leaving site-specific architecture in your hands.
Requirements
- Go 1.25.3 or newer
Features
- File primitives:
WriteIfChanged,CopyFileIfChanged,EnsureDir - HTML templating helpers with pluggable
template.FuncMap - Markdown rendering via Goldmark with GitHub-flavored extensions
- Safe parallel execution with panic capture
- Translation loaders for JSON/YAML and template helper functions
- Lightweight logging around build steps
Quick Start
go get github.com/benwmaddox/foundry
package main
import (
"html/template"
"path/filepath"
"github.com/benwmaddox/foundry"
)
func main() {
_ = foundry.WithStep("build site", func() error {
translations, err := foundry.LoadTranslations("i18n", "en")
if err != nil {
return err
}
tmpl, err := foundry.LoadTemplates("templates/*.html", foundry.TemplateFuncs(translations))
if err != nil {
return err
}
pages := []template.HTML{ /* site-defined data */ }
return foundry.ForEachParallel(pages, 4, func(body template.HTML) {
out := filepath.Join("dist", "index.html")
if err := foundry.WriteIfChanged(out, []byte(body)); err != nil {
panic(err)
}
})
})
}
See integration_test.go for a complete, runnable example of a multilingual site build.
License
MIT © Ben W. Maddox
Documentation
¶
Index ¶
- func CopyFileIfChanged(srcPath string, dstPath string) error
- func EnsureDir(dir string) error
- func ForEachParallel[T any](items []T, workers int, fn func(T)) error
- func LoadTemplates(glob string, funcs template.FuncMap) (*template.Template, error)
- func MarkdownToHTML(src []byte) ([]byte, error)
- func RenderTemplate(t *template.Template, name string, data any) ([]byte, error)
- func SetStepLogger(l *log.Logger)
- func TemplateFuncs(t Translations) template.FuncMap
- func WithStep(name string, fn func() error) error
- func WriteIfChanged(path string, content []byte) error
- type Translations
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CopyFileIfChanged ¶
CopyFileIfChanged copies the file from srcPath to dstPath only if the destination content differs from the source.
func ForEachParallel ¶
ForEachParallel applies fn to every item using up to workers goroutines. It returns an error if workers is less than one, fn is nil, or if fn panics.
func LoadTemplates ¶
LoadTemplates parses all templates matching the provided glob expression. The returned template includes any funcs supplied via funcs.
func MarkdownToHTML ¶
MarkdownToHTML converts Markdown bytes to HTML output using a standard, CommonMark-compliant renderer with a handful of ergonomic extensions enabled.
func RenderTemplate ¶
RenderTemplate executes the named template with the supplied data and returns the rendered bytes.
func SetStepLogger ¶
SetStepLogger allows tests to redirect WithStep logging. Production callers do not generally need this.
func TemplateFuncs ¶
func TemplateFuncs(t Translations) template.FuncMap
TemplateFuncs exposes translation helper functions to Go templates. When a key is missing the key itself is returned unless a fallback string is provided as the first variadic argument.
func WithStep ¶
WithStep logs the beginning and completion of a named operation. It always executes fn and returns its error, ensuring consistent timing output.
func WriteIfChanged ¶
WriteIfChanged ensures path exists and only writes the provided content to path when the bytes differ from the existing file. Writes are performed atomically to avoid partially written files when the process is interrupted.
Types ¶
type Translations ¶
Translations represents a map of translation keys to localized strings.
func LoadTranslations ¶
func LoadTranslations(dir string, lang string) (Translations, error)
LoadTranslations looks for translation data inside dir for the specified language. It supports .json, .yaml, and .yml files named <lang>.<ext>. Missing files yield an empty translation map.
func (Translations) Clone ¶
func (t Translations) Clone() Translations
Clone returns a shallow copy of the translation map. Mutating the clone does not affect the original map.
Source Files