sg

README

sg - another shitty static site generator

See github.com/ml8/ml8.github.io for an example.

Input site structure:

• sg.yaml -- Site config. Fields defined in Site.

• templates/ -- Directory of html templates. Use Go's html/template. Fields available to templates are those in RenderContext (and transitive references therefrom).

• pages/ -- Directory of pages. Pages are either raw HTML (that may include template code), markdown files that are rendered, or plain files.

  • Markdown files must include some frontmatter (fields from Page) metadata.

To generate the site, supply the input directory containing the site structure and an output directory to render to. Optionally supply -w to watch the input directory or -s to serve a preview locally after rendering (-w implies -s):

sg -i input_dir -o output_dir

Renderer can be used directly. OfflineRenderer renders a site in one-shot, while OnlineRenderer watches an input directory and renders as files arrive.

Documentation

Index

• Variables
• type Config
• type OfflineRenderer
  • func (r *OfflineRenderer) Render() error
• type OnlineRenderer
  • func (r *OnlineRenderer) Render() (err error)
• type Page
  • func (p *Page) Content() (template.HTML, error)
  • func (p *Page) RawContent() ([]byte, error)
• type RenderContext
  • func (ctx RenderContext) PageReference(slug string) (*Page, error)
  • func (ctx RenderContext) Pages() []*Page
  • func (ctx RenderContext) RenderPage(p *Page) ([]byte, error)
  • func (ctx RenderContext) SlugURL(slug string) (string, error)
  • func (ctx RenderContext) Tags() []string
• type Renderer
• type Set
  • func NewSet[T comparable]() *Set[T]
  • func (s *Set[T]) Add(k T)
  • func (s *Set[T]) AddAll(k ...T)
  • func (s *Set[T]) Elements() iter.Seq[T]
  • func (s *Set[T]) Has(k T) bool
  • func (s *Set[T]) Remove(k T) bool
  • func (s *Set[T]) Size() int
  • func (s *Set[T]) Slice() []T
• type Site
  • func (s *Site) AddPage(p *Page)
  • func (s *Site) AddTemplate(key string, byts []byte) error
  • func (s *Site) PageByPath(path string) (*Page, error)
  • func (s *Site) PageBySlug(slug string) (*Page, error)
  • func (s *Site) Pages() []*Page
  • func (s *Site) RemovePageByPath(path string) *Page
  • func (s *Site) Tag(tag string) ([]*Page, error)
  • func (s *Site) Tags() []string
  • func (s *Site) Template(key string) (*template.Template, error)
  • func (s *Site) Type(typ string) ([]*Page, error)

Variables

var (
	// Rendering errors
	ErrTemplateNotFound = errors.New("template not found")
	ErrSlugNotFound     = errors.New("slug not found")
	ErrPathNotFound     = errors.New("path not found")
	ErrTagNotFound      = errors.New("tag not found")
	ErrTypeNotFound     = errors.New("type not found")

	// Page validation/parsing errors.
	ErrMissingSlug        = errors.New("invalid slug")
	ErrMissingType        = errors.New("invalid type")
	ErrMissingPath        = errors.New("missing path")
	ErrMissingTitle       = errors.New("missing title")
	ErrMissingFrontmatter = errors.New("missing frontmatter")

	// Frontmatter delimiter
	FrontmatterDelimiter = []byte("---")
)

Types

type Config

type Config struct {
	InputDir        string
	OutputDir       string
	UseLocalRootUrl bool // if true, use http://localhost:8080 as the root url
	QuiescentSecs   int  // period to wait before re-rendering pages on a template change
}

Config for sites.

type OfflineRenderer

type OfflineRenderer struct {
	Config Config
}

Render a site in one-shot mode.

func (*OfflineRenderer) Render

func (r *OfflineRenderer) Render() error

Renders the site and returns any error generated during rendering. Renders in one-shot and returns when rendering is complete.

type OnlineRenderer

type OnlineRenderer struct {
	Config Config
	// contains filtered or unexported fields
}

Renders a site in online mode. Watches the input directory for changes and renders them as files are changed. When a template changes, all pages are re-rendered currently. Re-rendering after a template change waits for a quiescence period to allow time for intital rendering of the site.

TODO: only re-render when a page is affected by the template change.

func (*OnlineRenderer) Render

func (r *OnlineRenderer) Render() (err error)

Start rendering. Watches the filesystem for any updates and renders updates as they arrive. Does not return unless rendering failed to start.

type Page

type Page struct {
	// Required fields.
	FilePath  string // filename relative to the input directory
	UrlPath   string // url relative to the site root
	Slug      string `yaml:"slug"`
	Title     string `yaml:"title"`
	Type      string `yaml:"type"`
	IsRaw     bool
	OrderHint int

	// Fields for markdown pages.
	Draft    bool      `yaml:"draft"`
	Date     time.Time `yaml:"date"`
	Tags     []string  `yaml:"tags"`
	Ordering string    `yaml:"ordering"`
	// contains filtered or unexported fields
}

A Page.

func (*Page) Content

func (p *Page) Content() (template.HTML, error)

Return the content of the page, converted to HTML. Reads page from filesystem.

func (*Page) RawContent

func (p *Page) RawContent() ([]byte, error)

Get the raw content from the file. Reads the file each call.

type RenderContext

type RenderContext struct {
	Site *Site
	Page *Page
	// contains filtered or unexported fields
}

Context within which a page is rendered and defines top-level functions that can be called from the template.

func (RenderContext) PageReference

func (ctx RenderContext) PageReference(slug string) (*Page, error)

Get a page, given a slug.

func (RenderContext) Pages

func (ctx RenderContext) Pages() []*Page

All pages from the site.

func (RenderContext) RenderPage

func (ctx RenderContext) RenderPage(p *Page) ([]byte, error)

func (RenderContext) SlugURL

func (ctx RenderContext) SlugURL(slug string) (string, error)

URL for a given slug.

func (RenderContext) Tags

func (ctx RenderContext) Tags() []string

All tags from the site.

type Renderer

type Renderer interface {
	Render() error
}

Generic renderer interface.

type Set

type Set[T comparable] struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

Simple set implementation.

func NewSet

func NewSet[T comparable]() *Set[T]

func (*Set[T]) Add

func (s *Set[T]) Add(k T)

func (*Set[T]) AddAll

func (s *Set[T]) AddAll(k ...T)

func (*Set[T]) Elements

func (s *Set[T]) Elements() iter.Seq[T]

func (*Set[T]) Has

func (s *Set[T]) Has(k T) bool

func (*Set[T]) Remove

func (s *Set[T]) Remove(k T) bool

func (*Set[T]) Size

func (s *Set[T]) Size() int

func (*Set[T]) Slice

func (s *Set[T]) Slice() []T

type Site

type Site struct {
	sync.Mutex

	Title   string `yaml:"title"`
	RootUrl string `yaml:"root_url"`
	// contains filtered or unexported fields
}

A Site.

func (*Site) AddPage

func (s *Site) AddPage(p *Page)

Add a page to the site.

func (*Site) AddTemplate

func (s *Site) AddTemplate(key string, byts []byte) error

Add a template keyed by the given string.

func (*Site) PageByPath

func (s *Site) PageByPath(path string) (*Page, error)

Lookup page by input path.

func (*Site) PageBySlug

func (s *Site) PageBySlug(slug string) (*Page, error)

Lookup page by slug.

func (*Site) Pages

func (s *Site) Pages() []*Page

Retrieve all pages.

func (*Site) RemovePageByPath

func (s *Site) RemovePageByPath(path string) *Page

Remove the page with the given path and return the removed page. If page does not exist, returns nil.

func (*Site) Tag

func (s *Site) Tag(tag string) ([]*Page, error)

Get all pages with the given tag.

func (*Site) Tags

func (s *Site) Tags() []string

Retrieve all tags.

func (*Site) Template

func (s *Site) Template(key string) (*template.Template, error)

Look up the tempate associated with the given key.

func (*Site) Type

func (s *Site) Type(typ string) ([]*Page, error)

Get all pages with the given type.