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 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 WithBaseOption ¶ added in v2.1.0

func WithBaseOption(baseOption BaseOption) GeneratorOption

WithBaseOption wraps a BaseOption as a GeneratorOption so it can be passed to generator constructors that accept GeneratorOption values. Use this when you have a BaseOption (e.g. from WithBlogRoot) and need to supply it alongside other GeneratorOptions.

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 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 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,
    }),
)