Documentation
¶
Overview ¶
Package ssg creates pages from HTML templates and markdown files.
The content directory root may contain:
- html template files
- one folder for each page, containing markdown files whose filename root is the language prefix, like "en.md"
- static assets (files and folders) which are copied verbatim (see Keep)
The output file structure is like "/en/page.html". The files contain static src and href paths.
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 [WriteFiles]. Because it partly follows symlinks, you should use this package on trusted input only.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var Keep = []string{
"ads.txt",
"app-ads.txt",
"assets",
"files",
"images",
"static",
}
Functions ¶
func CopyFS ¶
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.
Types ¶
type LangOption ¶
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
Path string // without language prefix, for language buttons and hreflang
Title string // for <title>
}
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 // consider wrapping httputil.ModTimeFS around it
Pages map[string]struct {
Template *template.Template
Data TemplateData
}
PageData func(r *http.Request, data TemplateData) any // Must return TemplateData or a struct that embeds it. The http request may be needed to get session data.
Static []string // url and filesystem paths
}
func MakeWebsite ¶
func (Website) 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 WriteFiles, 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) WriteFiles ¶
WriteFiles 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, err := ssg.MakeWebsite(os.DirFS("./example.com"), nil, langs, nil)
if err != nil {
panic(err)
}
err = ws.WriteFiles("/tmp/build/example.com")
if err != nil {
panic(err)
}
ssg.ListenAndServe("/tmp/build/example.com")
}
Source Files