config

func WithBlogRoot ¶ added in v2.1.0

func WithBlogRoot(root string) BaseOption

WithBlogRoot returns an Option that sets the blog's root path.

The blog root is used in generated HTML pages and templates.

Example usage:

gen := generator.New(fsys, renderer, config.WithBlogRoot("/blog/"))

func WithLogger ¶ added in v2.5.0

func WithLogger(l *slog.Logger) BaseOption

WithLogger returns a BaseOption that sets the structured logger used by the component.

Passing nil is permitted and is treated the same as not supplying the option: the component falls back to log/slog.Default at construction time.

Example usage:

import "log/slog"

logger := slog.New(slog.NewTextHandler(os.Stdout, nil))

gen := generator.New(fsys, renderer, config.WithLogger(logger).AsGeneratorOption())
w, err := watcher.New("posts/", config.WithLogger(logger))
writer := outputter.NewDirectoryWriter("output/", config.WithLogger(logger).AsGeneratorOption())

func WithCacheControl ¶

func WithCacheControl(ttl time.Duration) BaseServerOption

WithCacheControl returns a BaseServerOption that sets the Cache-Control max-age TTL on all HTTP responses served by the server.

When ttl > 0 the server adds "Cache-Control: public, max-age=<N>" to every response, where N is ttl truncated to whole seconds. Setting ttl to 0 (or any non-positive value) disables the header so no Cache-Control is sent.

The default (when this option is not supplied) is one hour.

Example usage:

cfg := config.ServerConfig{
    Server: []config.BaseServerOption{
        config.WithCacheControl(24 * time.Hour), // cache for one day
    },
}

To disable caching entirely:

cfg.Server = append(cfg.Server, config.WithCacheControl(0))

func WithHealthChecks ¶

func WithHealthChecks() BaseServerOption

WithHealthChecks returns a BaseServerOption that enables health-check endpoints on the HTTP server.

When enabled, the server exposes three unauthenticated endpoints:

• GET /healthz/live — always 200 OK (process is alive)
• GET /healthz/ready — 200 OK once posts and templates have loaded; 503 Service Unavailable while starting up or if loading failed
• GET /healthz/startup — same semantics as /healthz/ready

The server binds the HTTP listener before initialising content when health checks are enabled, allowing probes to observe the startup state. Response bodies are plain text ("ok" or an error description).

Health checks are disabled by default.

Example usage:

cfg := config.ServerConfig{
    Server: []config.BaseServerOption{
        config.WithHealthChecks(),
    },
}

func WithHost ¶ added in v2.1.0

func WithHost(host string) BaseServerOption

WithHost returns a BaseServerOption that sets the HTTP server bind address.

Example usage:

cfg := config.ServerConfig{
    Server: []config.BaseServerOption{
        config.WithHost("127.0.0.1"),
    },
}

func WithMiddleware ¶ added in v2.1.0

func WithMiddleware(mw ...middleware.Middleware) BaseServerOption

WithMiddleware returns a BaseServerOption that adds HTTP middleware to the server.

Middleware are applied in the order provided. The first middleware in the list will be the outermost wrapper (executed first for requests, last for responses). Multiple calls to WithMiddleware append to the middleware chain.

Example usage:

import (
    "github.com/harrydayexe/GoWebUtilities/logging"
    "github.com/harrydayexe/GoWebUtilities/middleware"
)

cfg := config.ServerConfig{
    Server: []config.BaseServerOption{
        config.WithPort(8080),
        config.WithMiddleware(
            logging.New(logger),      // Built-in logging
            customAuthMiddleware,     // Custom middleware
        ),
    },
}

All middleware must be safe for concurrent use by multiple goroutines.

func WithPort ¶ added in v2.1.0

func WithPort(port int) BaseServerOption

WithPort returns a BaseServerOption that sets the HTTP server listen port.

Example usage:

cfg := config.ServerConfig{
    Server: []config.BaseServerOption{
        config.WithPort(8080),
    },
}

func WithBaseURL ¶

func WithBaseURL(url string) GeneratorOption

WithBaseURL returns a GeneratorOption that sets the site's absolute base URL.

The base URL is prepended to site-relative paths to produce fully-qualified URLs for RSS/Atom feed items. It must contain only the scheme and host (e.g. "https://example.com"). If the blog lives under a sub-path, configure that via WithBlogRoot — including the path in the base URL produces duplicated path segments in every feed URL.

Trailing slashes are trimmed before the base URL is used, so "https://example.com/" and "https://example.com" are equivalent.

When no base URL is configured, feed generation is silently skipped (see WithDisableFeeds to explicitly opt out instead).

Example usage:

gen := generator.New(fsys, renderer, config.WithBaseURL("https://example.com"))

func WithCustomData ¶ added in v2.4.0

func WithCustomData(data map[string]any) GeneratorOption

WithCustomData returns a GeneratorOption that merges the supplied map into the custom data available to all page templates as {{ .Custom.key }}.

The map is exposed on github.com/harrydayexe/GoBlog/v2/pkg/models.BaseData.Custom and is available in every rendered page: post, index, tag, and tags-index.

Multiple calls to WithCustomData accumulate: keys are merged in the order the options are applied, with later values overwriting earlier ones for the same key. Templates should guard access with {{ with .Custom }} or {{ if .Custom }} when the field may be nil (i.e. when no WithCustomData option was supplied).

The same map instance is shared across all pages rendered in a single Generate call. Callers must not mutate the map after passing it to WithCustomData. Values stored in the map must be safe for concurrent reads because the HTTP server may render multiple pages in parallel.

Security ¶

Store only plain, immutable values (strings, numbers, booleans) in the map. Do not pre-wrap values in html/template.HTML, html/template.JS, html/template.JSStr, html/template.URL, html/template.CSS, or html/template.HTMLAttr: those types signal to html/template that the value is already safe and bypass contextual auto-escaping, creating an XSS sink if the value originates from user-controlled input. Let html/template escape values at render time instead.

Do not construct custom data from untrusted input at request time. This map is intended for static, developer-controlled values only.

Example usage:

gen := generator.New(fsys, renderer,
    config.WithCustomData(map[string]any{
        "author":      "Jane Smith",
        "analyticsID": "UA-12345",
    }),
)

In a template:

{{ with .Custom }}
    <meta name="author" content="{{ .author }}">
{{ end }}

func WithDisableFeeds ¶

func WithDisableFeeds() GeneratorOption

WithDisableFeeds returns a GeneratorOption that disables all feed generation.

By default, GoBlog generates RSS 2.0 and Atom feeds when a base URL is configured via WithBaseURL. Applying this option suppresses that behaviour entirely, regardless of whether a base URL is set.

When applied to the outputter, no feed files are written. Templates receive BaseData.FeedsEnabled = false and will suppress any feed discovery links and visible RSS navigation.

Example usage:

gen := generator.New(fsys, renderer, config.WithDisableFeeds())
writer := outputter.NewDirectoryWriter("output/", config.WithDisableFeeds())

func WithDisableReadingTime ¶ added in v2.3.0

func WithDisableReadingTime() GeneratorOption

WithDisableReadingTime returns a GeneratorOption that disables reading time estimation on posts.

When applied to a generator, Post.ReadingTimeMinutes will remain zero for all posts. The default templates guard the "· N min read" annotation with {{if .Post.ReadingTimeMinutes}}, so setting this option suppresses the display without requiring template changes.

Example usage:

gen := generator.New(fsys, renderer, config.WithDisableReadingTime())

func WithDisableTags ¶ added in v2.3.0

func WithDisableTags() GeneratorOption

WithDisableTags returns a GeneratorOption that disables all tag-related output.

When applied to a generator, it will skip rendering tag pages and the tags index. Post tag slices are cleared so that the default templates do not render per-post tag pills. When applied to an outputter, it will skip creating the tags directory. When applied to the HTTP server, /tags routes are not registered.

Example usage:

gen := generator.New(fsys, renderer, config.WithDisableTags())
writer := outputter.NewDirectoryWriter("output/", config.WithDisableTags())

func WithEnvironment ¶ added in v2.1.2

func WithEnvironment(env string) GeneratorOption

WithEnvironment returns a GeneratorOption that sets the runtime environment surfaced to all page templates via models.BaseData.Environment. Callers are responsible for supplying a validated value (e.g. via gowebutilities config.ParseConfig with EnvironmentConfig).

Example usage:

gen := generator.New(fsys, renderer, config.WithEnvironment("production"))

func WithFeedPostLimit ¶

func WithFeedPostLimit(limit int) GeneratorOption

WithFeedPostLimit returns a GeneratorOption that sets the maximum number of posts included in each generated feed.

A value of 0 or any negative number means unlimited — all posts are included. The same limit applies to the site-wide feed and every per-tag feed. When this option is not set, the library applies no limit (the goblog CLI uses a default of 10).

Example usage:

gen := generator.New(fsys, renderer,
    config.WithBaseURL("https://example.com"),
    config.WithFeedPostLimit(20),
)

func WithHTMLPaths ¶ added in v2.4.0

func WithHTMLPaths() GeneratorOption

WithHTMLPaths returns a GeneratorOption that switches BaseData.Path to use .html-suffixed file paths instead of clean URLs.

This is automatically applied by the goblog generate CLI so that canonical URLs in static output match the actual .html files written to disk. Library users serving content via pkg/server should leave this option off; the server accepts both clean URLs and .html URLs via its built-in StripHTMLExtension middleware.

Path values with this option enabled:

BlogRoot = "/"            BlogRoot = "/blog/"
Index:   /index.html      /blog.html
Post:    /posts/slug.html  /blog/posts/slug.html
Tag:     /tags/go.html    /blog/tags/go.html
TagsIdx: /tags.html       /blog/tags.html

Example usage:

gen := generator.New(fsys, renderer, config.WithHTMLPaths())

func WithRawOutput ¶

func WithRawOutput() GeneratorOption

WithRawOutput returns an Option that enables raw HTML output mode.

When this option is applied to a generator, it will produce HTML content without template wrapping - only the Markdown-to-HTML conversion is performed. When applied to an outputter, it will skip creating the tags directory.

This is useful for scenarios where you want to integrate GoBlog's HTML output into your own templates or existing site structure.

Example usage:

gen := generator.New(fsys, nil, config.WithRawOutput())
writer := outputter.NewDirectoryWriter("output/", config.WithRawOutput())

When using WithRawOutput on the generator, no template renderer is needed because templates are bypassed entirely; pass nil as the renderer.

func WithSiteTitle ¶ added in v2.0.5

func WithSiteTitle(title string) GeneratorOption

WithSiteTitle returns an Option that sets the site title.

The site title is used in generated HTML pages and templates.

Example usage:

gen := generator.New(fsys, renderer, config.WithSiteTitle("My Blog"))

func WithFuncs ¶ added in v2.4.0

func WithFuncs(funcs template.FuncMap) RendererOption

WithFuncs returns a RendererOption that merges the supplied functions into the template FuncMap used by github.com/harrydayexe/GoBlog/v2/pkg/generator.NewTemplateRenderer.

The built-in helpers available to all templates are:

formatDate(t time.Time) string   formats t as "January 2, 2006"
shortDate(t time.Time) string    formats t as "Jan 2, 2006"
year() int                       returns the current calendar year

If a key in funcs matches one of those built-in names, the supplied function replaces the built-in and a warning is logged via slog. This allows intentional overrides (for example, substituting your own date format), but will also suppress default template behaviour if done accidentally. Check against the list above before registering a function to avoid unintentional collisions.

Multiple calls to WithFuncs accumulate: functions are merged in the order the options are applied, with later registrations overwriting earlier ones for the same key.

Security ¶

html/template's contextual auto-escaping is bypassed for any function that returns one of the following pre-sanitised types: html/template.HTML, html/template.JS, html/template.JSStr, html/template.URL, html/template.CSS, or html/template.HTMLAttr. Never use those return types with values derived from user-controlled input, as doing so opts the value out of escaping and creates an XSS sink.

Example usage:

import (
    "strings"
    "html/template"
    "github.com/harrydayexe/GoBlog/v2/pkg/config"
    "github.com/harrydayexe/GoBlog/v2/pkg/generator"
    "github.com/harrydayexe/GoBlog/v2/pkg/templates"
)

renderer, err := generator.NewTemplateRenderer(
    templates.Default,
    config.WithFuncs(template.FuncMap{
        "upper": strings.ToUpper,
    }),
)

func WithDebounce ¶ added in v2.5.0

func WithDebounce(d time.Duration) WatcherOption

WithDebounce returns a WatcherOption that sets the event debounce window. File-system events that arrive within this duration of each other are coalesced into a single onChange invocation. Defaults to 300ms.

Example usage:

w, err := watcher.New("posts/", config.WithDebounce(500*time.Millisecond))