ssg

Documentation

Overview

Package ssg creates both static and dynamic sites from translated HTML templates and markdown files.

The content directory root may contain:

• html template files
• one folder for each html page, containing markdown files whose filename root is the language prefix, like "en.md"
• files and folders which are copied verbatim (see Keep)

The output is like "/en/page.html".

Note that "gotext update" requires a Go module and package for merging translations, accessing message.DefaultCatalog and writing catalog.go. While gotext-update-templates has been extended to accept additional directories, a root module and package is still required for static site generation.

For symlink support see [Handler] and [StaticHTML]. Because it partly follows symlinks, you should use this package on trusted input only.

Index

• Variables
• func CopyFS(dst string, fsys fs.FS, fspath string) error
• func ListenAndServe(dir string)
• type LangOption
  • func LangOptions(langs lang.Languages, selected lang.Lang) []LangOption
• type TemplateData
  • func MakeTemplateData(langs lang.Languages, r *http.Request) TemplateData
  • func (td TemplateData) Hreflangs() template.HTML
• type Website
  • func MakeWebsite(fsys fs.FS, add *template.Template, langs lang.Languages) (*Website, error)
  • func Must(ws *Website, err error) *Website
  • func (ws Website) Handler(makeTemplateData func(*http.Request, TemplateData) any, next http.Handler) http.Handler
  • func (ws Website) StaticHTML(outDir string, onion bool)

Examples

• Website.StaticHTML

Variables

var Keep = []string{
	"ads.txt",
	"app-ads.txt",
	"assets",
	"files",
	"images",
	"sites",
	"static",
}

Functions

func CopyFS

func CopyFS(dst string, fsys fs.FS, fspath string) error

like https://github.com/golang/go/issues/62484#issue-1884498794 but with error handling, custom walk root, and follows symlinks

func ListenAndServe

func ListenAndServe(dir string)

ListenAndServe provides an easy way to preview a static site with absolute src and href paths.

Types

type LangOption

type LangOption struct {
	BCP47    string
	Name     string
	Prefix   string
	Selected bool
}

LangOption should be used in templates.

func LangOptions

func LangOptions(langs lang.Languages, selected lang.Lang) []LangOption

SelectLanguage returns a [Language] slice. If if only one language is present, the slice will be empty.

type TemplateData

type TemplateData struct {
	lang.Lang
	Languages []LangOption // usually empty if only one language is defined
	Onion     bool
	Path      string // without language prefix, for language buttons and hreflang
	Title     string // for <title>
}

func MakeTemplateData

func MakeTemplateData(langs lang.Languages, r *http.Request) TemplateData

func (TemplateData) Hreflangs

func (td TemplateData) Hreflangs() template.HTML

Hreflangs returns <link hreflang> elements for every td.Language, including the selected language.

See also: https://developers.google.com/search/blog/2011/12/new-markup-for-multilingual-content

type Website

type Website struct {
	Fsys    fs.FS
	Dynamic map[string]struct {
		Template *template.Template
		Data     TemplateData
	}
	Static []string // url and filesystem paths
}

func MakeWebsite

func MakeWebsite(fsys fs.FS, add *template.Template, langs lang.Languages) (*Website, error)

func Must

func Must(ws *Website, err error) *Website

func (Website) Handler

func (ws Website) Handler(makeTemplateData func(*http.Request, TemplateData) any, next http.Handler) http.Handler

Handler returns a HTTP handler which serves content from fsys. It optionally accepts an additional HTML template and a function which makes custom template data. For compatibility with StaticHTML, the custom template data struct should embed TemplateData.

Note that embed.FS does not support symlinks. If you use symlinks to share content, consider building a go:generate workflow which calls "cp --dereference".

func (Website) StaticHTML

func (ws Website) StaticHTML(outDir string, onion bool)

StaticHTML creates static HTML files. Templates are executed with TemplateData. Symlinks are dereferenced.

Example

package main

import (
	"os"

	"github.com/dys2p/eco/lang"
	"github.com/dys2p/eco/ssg"
)

func main() {
	langs := lang.MakeLanguages(nil, "de", "en")
	ws := ssg.Must(ssg.MakeWebsite(os.DirFS("./example.com"), nil, langs))
	ws.StaticHTML("/tmp/build/example.com", false)

	ssg.ListenAndServe("/tmp/build/example.com")
}