Documentation
¶
Overview ¶
Package config provides common configuration options used across the GoBlog generator and outputter packages.
The package implements the functional options pattern for configuration, allowing packages to accept both required positional parameters and optional configuration via option functions.
Functional Options Pattern ¶
Configuration is applied through Option values that can be passed to constructors. Each option function modifies specific configuration fields:
gen := generator.New(postsFS, nil, config.WithRawOutput())
writer := outputter.NewDirectoryWriter("output/", config.WithRawOutput())
Options are implemented as structs containing functions that modify embedded configuration types. This pattern allows for:
- Backward compatibility when adding new options
- Clear, self-documenting API calls
- Optional parameters without function overloading
Available Options ¶
WithRawOutput() enables raw HTML output mode without template wrapping. When enabled in the generator, markdown is converted to HTML without inserting it into page templates. When enabled in the outputter, the tags directory is not created.
WithTemplatesDir(fs.FS) specifies a custom filesystem containing templates to use for rendering blog pages. This allows you to provide your own template files instead of using the defaults.
WithBlogRoot(path string) sets the root path for the blog when deploying at a subdirectory rather than domain root. For example, use "/blog/" when deploying at example.com/blog/. This ensures all generated links in templates use the correct base path. Default is "/" for root deployment.
Usage Examples ¶
Basic usage with a single option:
fsys := os.DirFS("posts/")
gen := generator.New(fsys, nil, config.WithRawOutput())
Multiple options can be combined:
renderer, _ := generator.NewTemplateRenderer(templates.Default)
gen := generator.New(fsys, renderer,
config.WithRawOutput(),
config.WithSiteTitle("My Blog"),
)
Configuring blog root for subdirectory deployment:
renderer, _ := generator.NewTemplateRenderer(templates.Default)
gen := generator.New(fsys, renderer,
config.WithBlogRoot("/blog/"),
)
Concurrency ¶
Option values are safe to create and use concurrently. Configuration structs that embed RawOutput and TemplatesDir are safe to read concurrently once created, but should not be modified after construction.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BaseOption ¶ added in v2.1.0
type BaseOption struct {
WithBlogRootFunc func(v *BlogRoot)
}
BaseOption represents a configuration option that can be applied to many different instances during construction.
Options use the functional options pattern, where each option function returns an BaseOption struct containing one or more function pointers that modify specific configuration fields.
This type should not be constructed directly by users. Instead, use the provided option functions like WithBlogRoot().
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/"))
type BaseServerOption ¶ added in v2.1.0
type BaseServerOption struct {
BaseOption
WithPortFunc func(v *Port)
WithHostFunc func(v *Host)
WithMiddlewareFunc func(mw *[]middleware.Middleware)
}
BaseServerOption represents a configuration option for the HTTP server. Options use the functional options pattern; each value carries a function pointer that modifies a specific server setting.
This type should not be constructed directly. Use the provided option functions: WithPort, WithHost, and WithMiddleware.
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),
},
}
type BlogRoot ¶ added in v2.1.0
type BlogRoot string
BlogRoot is a configuration type that holds the blog's root path
This type is typically embedded in generator configuration structs and should be set using the WithBlogRoot() option function.
func (BlogRoot) AsOption ¶ added in v2.1.0
func (o BlogRoot) AsOption() BaseOption
type Environment ¶ added in v2.1.2
type Environment struct{ Environment string }
Environment is a configuration type holding the runtime environment name (e.g. "local", "test", "production"). It is exposed to templates via models.BaseData.Environment so users can branch on environment.
func (Environment) AsOption ¶ added in v2.1.2
func (o Environment) AsOption() GeneratorOption
type EnvironmentConfig ¶ added in v2.1.2
type EnvironmentConfig struct {
// Environment is read from the ENVIRONMENT env var. Valid values are
// "local" (default), "test", and "production".
Environment gwucfg.Environment `env:"ENVIRONMENT" envDefault:"local"`
}
EnvironmentConfig reads the runtime environment from the ENVIRONMENT env var via gowebutilities config.ParseConfig. Only the Environment field is parsed, so it does not conflict with the CLI-flag-driven port/timeout settings.
func (EnvironmentConfig) Validate ¶ added in v2.1.2
func (c EnvironmentConfig) Validate() error
Validate ensures Environment is one of the gowebutilities-defined constants.
type GeneratorOption ¶ added in v2.1.0
type GeneratorOption struct {
BaseOption
WithRawOutputFunc func(v *RawOutput)
WithSiteTitleFunc func(v *SiteTitle)
WithEnvironmentFunc func(v *Environment)
}
GeneratorOption represents a configuration option that can be applied to generator or outputter instances during construction.
Options use the functional options pattern, where each option function returns an GeneratorOption struct containing one or more function pointers that modify specific configuration fields.
This type should not be constructed directly by users. Instead, use the provided option functions like WithRawOutput() and WithTemplatesDir().
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 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 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"))
type Host ¶ added in v2.1.0
type Host string
Host is the network address the HTTP server binds to. An empty Host binds to all available network interfaces.
type RawOutput ¶ added in v2.0.5
type RawOutput struct{ RawOutput bool }
RawOutput is a configuration type that controls whether HTML output is generated with or without template wrapping.
When RawOutput is true:
- The generator produces only Markdown-to-HTML conversion without templates
- The outputter skips creating the tags directory
- Individual post files contain raw HTML fragments
This type is typically embedded in generator and outputter configuration structs and should be set using the WithRawOutput() option function.
func (RawOutput) AsOption ¶ added in v2.1.0
func (o RawOutput) AsOption() GeneratorOption
type ServerConfig ¶ added in v2.1.0
type ServerConfig struct {
Server []BaseServerOption
Gen []GeneratorOption
TemplateDir fs.FS
}
type SiteTitle ¶ added in v2.0.5
type SiteTitle struct{ SiteTitle string }
SiteTitle is a configuration type that holds the site's title.
This type is typically embedded in generator configuration structs and should be set using the WithSiteTitle() option function.
func (SiteTitle) AsOption ¶ added in v2.1.0
func (o SiteTitle) AsOption() GeneratorOption
Source Files