fest

README

FEST

Fantastically Easy Static-site with Templ (FEST) is a minimalistic static-site generator that integrates nicely with Go & Templ. It is aimed for Go developers to generate a static-website with existing Go libraries and available knowledge.

FEATURES

• Write static-site with Go.
• Use any Go libraries in its ecosystem and use it in your Go or Templ files.
• Lightweight and modular; only import Templ as dependency for the main package (fest).
• Routing feature that is inspired by router libraries, particularly Chi.

You can see the documentation/API references here.

INSTALL

Initialize your Go project.

go mod init my-project

Since FEST uses Templ, you need to install Templ first.

go install https://github.com/a-h/templ/tree/main/cmd/templ@latest

Then simply get the library by running go get.

go get github.com/zilllaiss/fest

USAGE

Write your templ files like usual. In this example, I make views/views.templ folder and file for it.

package views 

templ Index() {
    <h1>Hello, World</h1>
}

templ About(name string) {
    <h1>Hello</h1>
    <p>My name is {name}. I'm a Go developer</p>
}

templ Post(title, content string) {
    <h1>{ title }</h1>
    <article>{ content }</article>
}

Import it to your Go files and use it with FEST like a router!

package main

import (
	"context"
	"my-project/views"

	"github.com/a-h/templ"
	"github.com/zilllaiss/fest"
	"github.com/zilllaiss/fest/temfest"
)

func main() {
	// nil will use the default config.
	// By default, FEST will use the Working Directory as source,
	// unless overrided by configs or FEST_SRC environment variable.
	g := fest.NewGenerator(context.Background(), "My site", nil)

	// copy assets to the default destionation path. You can specify it with
	g.CopyDir("assets", "")
	g.CopyFile("404.html", "")

	// add global style in the header
	g.HeadBody.Head(
		// fest provides commonly used templates in temfest package
		temfest.ImportStyle("/assets/styles.css"),
		temfest.ImportStyle("/assets/nested/styles.css"),
	)

	// add homepage. This will use the site's name as Route title is not set
	g.AddRoute("/", views.Index())

	// set the page title. If not set, FEST will use the site's name by default
	g.AddRoute("/about", views.About("Zill_Laiss")).
		SetTitle("About Us")

	// you can use any templ component like templ.Raw
	g.AddRoute("/posts/first", templ.Raw("<h1>Hello</h1>")).
		SetTitle("First Post")

	// render all components
	if err := g.Generate(); err != nil {
		panic(err)
	}
}

Then run the binary to generate your website.

# if you haven't run templ generate already
templ generate && go run main.go

By default it is available in /dist folder inside your project directory.

See examples for more.

Multiple routes

// a simple blog post with title and content
type post struct {
	title, content string
}

func postsFn(ctx context.Context, rp *fest.RoutesParam[post]) (templ.Component, error) {
	// get the item passed from before
	p := rp.GetItem()
	// setting the slug with title
	rp.SetSlug(p.title)

	return views.Post(p.title, p.content), nil
}

// in the main funcion

posts := []post{
    {title: "second", content: "second post"},
    {title: "third", content: "third post"},
}

// this {s} is a slug and will be replaced, by default it is 1-based index
// of for each item captured from the slice passed, unless you override it with SetSlug.
// see postsFn below
fest.NewRoutesT("/posts/{s}", posts).AddToGenerator(g, postsFn)

LICENSE

MIT

Documentation

Overview

Package fest is the main fest package

Index

• func GetTitle(ctx context.Context) string
• type Generator
  • func NewGenerator(ctx context.Context, siteName string, config *GeneratorConfig) *Generator
  • func (g *Generator) AddRoute(path string, comp templ.Component) *Route
  • func (g *Generator) AddRouteFunc(path string, fn func(context.Context) (templ.Component, error)) *Route
  • func (g *Generator) Context() context.Context
  • func (g *Generator) CopyDir(src, dst string)
  • func (g *Generator) CopyFile(src, dst string)
  • func (g *Generator) Generate() error
• type GeneratorConfig
• type HeadBody
  • func (hb *HeadBody) Body(comps ...templ.Component)
  • func (hb *HeadBody) Head(comps ...templ.Component)
• type Pagination
• type Route
  • func (r *Route) BaseConfig(conf temfest.BaseConfig) *Route
  • func (r *Route) OverrideBase(comp templ.Component) *Route
  • func (r *Route) SetTitle(title string) *Route
• type RouteError
  • func (r RouteError) Error() string
  • func (r RouteError) Unwrap() error
• type RouteFunc
• type RouteParam
  • func (rp *RouteParam[T]) BaseConfig(conf temfest.BaseConfig)
  • func (rp *RouteParam[T]) GetItem() T
  • func (rp *RouteParam[T]) GetSlug() string
  • func (rp *RouteParam[T]) SetSlug(slug string)
  • func (rp *RouteParam[T]) SetTitle(title string)
• type Routes
  • func NewPaginatedRoutes[T any](path string, data []T, size int) *Routes[*Pagination[T]]
  • func NewRoutes(path string, slugs []string) *Routes[string]
  • func NewRoutesT[T any](path string, data []T) *Routes[T]
  • func (rs *Routes[T]) AddToGenerator(g *Generator, fn RouteFunc[T])
  • func (rs *Routes[T]) BaseConfig(conf temfest.BaseConfig) *Routes[T]
  • func (rs *Routes[T]) SetTitle(title string) *Routes[T]
• type SiteNameOption

Functions

func GetTitle

func GetTitle(ctx context.Context) string

GetTitle gets the current router's title.

Types

type Generator

type Generator struct {
	HeadBody HeadBody
	// contains filtered or unexported fields
}

Generator contains configuration for static files generation.

func NewGenerator

func NewGenerator(ctx context.Context, siteName string, config *GeneratorConfig) *Generator

NewGenerator creates a new generator. Use nil to use default configs

func (*Generator) AddRoute

func (g *Generator) AddRoute(path string, comp templ.Component) *Route

AddRoute adds a single route with the specified path that will generate a file from the component relative from the Generator destination.

func (*Generator) AddRouteFunc

func (g *Generator) AddRouteFunc(
	path string, fn func(context.Context) (templ.Component, error),
) *Route

AddRouteFunc adds a single route with the specified path that will generate a file from the component relative from the Generator destionation. All errors returned from this function will be handled in g.Generate method.

func (*Generator) Context

func (g *Generator) Context() context.Context

Context returns the generator context.

func (*Generator) CopyDir

func (g *Generator) CopyDir(src, dst string)

CopyDir copies src that is a directory to dst inside generated location. Will also copy the directory instead of the content-only. Relative from Source set of g.

func (*Generator) CopyFile

func (g *Generator) CopyFile(src, dst string)

CopyFile copies src that is a file to the dst inside generated location. Relative from Source of g.

func (*Generator) Generate

func (g *Generator) Generate() error

Generate generates all the components added to g.

type GeneratorConfig

type GeneratorConfig struct {
	// Don't use the built-in base template that is temfest.Base.
	// Note that utilities that modify temfest.Base will be no-op,
	// thus it is recommended to modify Head, Body, and BaseConfig instead.
	NoBase bool

	// Directory that will be used as root directory for finding necessary files.
	// By default it's "."
	Source string

	// Directory where static files will be generated. By default it's "./dist".
	Destination string

	// SiteNameOption is the position in the title where the site's
	// should be rendered. By default it's SiteNameBack.
	SiteNameOption SiteNameOption

	// Seperator is the string used to seperate page title with site's name.
	// By default it's " - ".
	Seperator string

	// BaseConfig is temfest.Base config.
	BaseConfig temfest.BaseConfig
}

GeneratorConfig is configurations for Generator.

type HeadBody

type HeadBody struct {
	// contains filtered or unexported fields
}

HeadBody represents `<head>` and `<body>` tags. It is mainly used to append.

func (*HeadBody) Body

func (hb *HeadBody) Body(comps ...templ.Component)

func (*HeadBody) Head

func (hb *HeadBody) Head(comps ...templ.Component)

type Pagination

type Pagination[T any] struct {
	// The current page number
	Current int

	// The total number of pages, or the last page.
	Total int

	// The chuck of data sliced with the set size from original data.
	Chunk []T
}

Pagination contains the information of the current page route.

type Route

type Route struct {
	HeadBody HeadBody
	// contains filtered or unexported fields
}

Route contains data necessary to generate a route.

func (*Route) BaseConfig

func (r *Route) BaseConfig(conf temfest.BaseConfig) *Route

func (*Route) OverrideBase

func (r *Route) OverrideBase(comp templ.Component) *Route

OverrideBase overrides the base component. Note that it must have the implemented templ { children... }

func (*Route) SetTitle

func (r *Route) SetTitle(title string) *Route

SetTitle sets the Route title. By default, the route will use site's name.

type RouteError

type RouteError struct {
	// contains filtered or unexported fields
}

func (RouteError) Error

func (r RouteError) Error() string

func (RouteError) Unwrap

func (r RouteError) Unwrap() error

type RouteFunc

type RouteFunc[T any] = func(context.Context, *RouteParam[T]) (templ.Component, error)

type RouteParam

type RouteParam[T any] struct {
	HeadBody HeadBody
	// contains filtered or unexported fields
}

RouteParam is the current route parameter.

func (*RouteParam[T]) BaseConfig

func (rp *RouteParam[T]) BaseConfig(conf temfest.BaseConfig)

BaseConfig sets the temfest.Base config for the current route. Unset/empty field will be no-op.

func (*RouteParam[T]) GetItem

func (rp *RouteParam[T]) GetItem() T

GetItem gets the current data item.

func (*RouteParam[T]) GetSlug

func (rp *RouteParam[T]) GetSlug() string

GetSlug gets the currently set slug.

func (*RouteParam[T]) SetSlug

func (rp *RouteParam[T]) SetSlug(slug string)

SetSlug sets the current slug.

func (*RouteParam[T]) SetTitle

func (rp *RouteParam[T]) SetTitle(title string)

SetTitle sets the current route title. It overrides the title sets for Routes.

type Routes

type Routes[T any] struct {
	HeadBody HeadBody
	// contains filtered or unexported fields
}

Routes generates multiple routes. User must call AddToGenerator in order to add the routes to the Generator.

func NewPaginatedRoutes

func NewPaginatedRoutes[T any](path string, data []T, size int) *Routes[*Pagination[T]]

NewPaginatedRoutes creates routes that will be paginated from data with specified size.

func NewRoutes

func NewRoutes(path string, slugs []string) *Routes[string]

NewRoutes creates routes from the data with specified size. By default, the slug will be the same as string item

func NewRoutesT

func NewRoutesT[T any](path string, data []T) *Routes[T]

NewRoutesT creates routes from the data with specified size. By default, the slug will be 1-based index of the item.

func (*Routes[T]) AddToGenerator

func (rs *Routes[T]) AddToGenerator(g *Generator, fn RouteFunc[T])

AddToGenerator adds routes to the set Generator.

func (*Routes[T]) BaseConfig

func (rs *Routes[T]) BaseConfig(conf temfest.BaseConfig) *Routes[T]

BaseConfig sets the temfest.Base config for the routes. Unset/empty field will be no-op.

func (*Routes[T]) SetTitle

func (rs *Routes[T]) SetTitle(title string) *Routes[T]

SetTitle sets each item route's title where `{s}` will be replaced with slug. If the title is empty, then only the site's name used. The default is "{s}"

type SiteNameOption

type SiteNameOption int

SiteNameOption specifies the title options

const (
	// Show the site title at the end
	SiteNameBack SiteNameOption = iota

	// Show the site title at the beginning
	SiteNameFront

	// Don't show site name in the title
	SiteNameNone
)