Documentation
¶
Overview ¶
Package config provides configuration loading and management for markata-go.
Package config provides configuration loading and management for markata-go.
Configuration File Formats ¶
The package supports three configuration formats:
- TOML (primary, recommended) using github.com/BurntSushi/toml
- YAML using gopkg.in/yaml.v3
- JSON using the standard library
All formats use a top-level "markata-go" key to namespace configuration:
# TOML example
[markata-go]
output_dir = "public"
url = "https://example.com"
# YAML example
markata-go:
output_dir: public
url: https://example.com
# JSON example
{"markata-go": {"output_dir": "public", "url": "https://example.com"}}
Configuration Discovery ¶
When no explicit config path is provided, the package searches for configuration files in the following order:
- ./markata-go.toml
- ./markata-go.yaml
- ./markata-go.yml
- ./markata-go.json
- ~/.config/markata-go/config.toml
If no configuration file is found, default values are used.
Environment Variable Overrides ¶
Configuration values can be overridden using environment variables with the MARKATA_GO_ prefix. Environment variables take precedence over file configuration.
Simple fields:
MARKATA_GO_OUTPUT_DIR=public MARKATA_GO_URL=https://example.com
Nested fields use underscores:
MARKATA_GO_GLOB_PATTERNS=posts/**/*.md,pages/*.md MARKATA_GO_FEED_DEFAULTS_ITEMS_PER_PAGE=20
Boolean values accept: "true", "1", "yes" for true; "false", "0", "no" for false.
List values are comma-separated:
MARKATA_GO_HOOKS=markdown,template,sitemap
Usage ¶
Basic usage:
// Load from default locations with env overrides
config, err := config.Load("")
// Load from specific file
config, err := config.Load("/path/to/config.toml")
// Load with defaults only
config, err := config.LoadWithDefaults()
// Load and validate
config, validationErrs, err := config.LoadAndValidate("/path/to/config.toml")
Merging Configurations ¶
The MergeConfigs function performs a deep merge of two configurations:
base := config.DefaultConfig()
override := &models.Config{OutputDir: "custom"}
merged := config.MergeConfigs(base, override)
String fields are overridden if non-empty. Integer fields are overridden if non-zero. Slices are replaced if non-empty. Feed formats are replaced if any format is enabled.
Validation ¶
Configurations can be validated to catch common errors and warnings:
errs := config.ValidateConfig(cfg)
if config.HasErrors(errs) {
// Handle errors
}
if config.HasWarnings(errs) {
// Handle warnings
}
Validation checks include:
- URL format validation
- Concurrency must be >= 0
- Feed slugs are required
- Warning on empty glob patterns
- Warning on feeds with no output formats
Index ¶
- Variables
- func AppendDisabledHooks(config *models.Config, hooks ...string)
- func AppendFeeds(config *models.Config, feeds ...models.FeedConfig)
- func AppendGlobPatterns(config *models.Config, patterns ...string)
- func AppendHooks(config *models.Config, hooks ...string)
- func ApplyEnvOverrides(config *models.Config) error
- func DefaultConfig() *models.Config
- func Discover() (string, error)
- func FromEnv() *models.Config
- func GetEnvValue(key string) (string, bool)
- func HasErrors(errs []error) bool
- func HasWarnings(errs []error) bool
- func Load(configPath string) (*models.Config, error)
- func LoadAndValidate(configPath string) (*models.Config, []error, error)
- func LoadFromString(data string, format Format) (*models.Config, error)
- func LoadWithDefaults() (*models.Config, error)
- func MergeConfigs(base, override *models.Config) *models.Config
- func MergeSlice[T any](base, override []T, appendMode bool) []T
- func MustLoad(configPath string) *models.Config
- func ParseJSON(data []byte) (*models.Config, error)
- func ParseTOML(data []byte) (*models.Config, error)
- func ParseYAML(data []byte) (*models.Config, error)
- func SetEnvValue(key, value string) error
- func SplitErrorsAndWarnings(errs []error) (errsOut, warnsOut []error)
- func StructToEnvKeys(prefix string, v interface{}) map[string]string
- func UnsetEnvValue(key string) error
- func ValidateAndWarn(config *models.Config, warnFunc func(error)) []error
- func ValidateConfig(config *models.Config) []error
- type Format
- type Path
- type ValidationError
Constants ¶
This section is empty.
Variables ¶
var ErrConfigNotFound = errors.New("no configuration file found")
ErrConfigNotFound is returned when no config file is found.
Functions ¶
func AppendDisabledHooks ¶
AppendDisabledHooks appends hooks to the configuration's DisabledHooks slice.
func AppendFeeds ¶
func AppendFeeds(config *models.Config, feeds ...models.FeedConfig)
AppendFeeds appends feeds to the configuration's Feeds slice.
func AppendGlobPatterns ¶
AppendGlobPatterns appends patterns to the configuration's GlobConfig.Patterns slice.
func AppendHooks ¶
AppendHooks appends hooks to the configuration's Hooks slice.
func ApplyEnvOverrides ¶
ApplyEnvOverrides applies environment variable overrides to a config. Environment variables are expected to follow the format MARKATA_GO_*. Nested keys use underscores: MARKATA_GO_FEEDS_DEFAULTS_ITEMS_PER_PAGE Boolean values: "true", "1", "yes" -> true; "false", "0", "no" -> false List values: comma-separated strings
func DefaultConfig ¶
DefaultConfig returns a Config with sensible default values.
func Discover ¶
Discover searches for a configuration file in the standard locations. It returns the path to the first config file found, or ErrConfigNotFound.
Discovery order:
- ./markata-go.toml
- ./markata-go.yaml (or .yml)
- ./markata-go.json
- ~/.config/markata-go/config.toml
func FromEnv ¶
FromEnv creates a Config entirely from environment variables. This is useful when no config file is available.
func GetEnvValue ¶
GetEnvValue returns the value of an environment variable with the MARKATA_GO_ prefix.
func HasErrors ¶
HasErrors returns true if the error slice contains any actual errors (not warnings).
func HasWarnings ¶
HasWarnings returns true if the error slice contains any warnings.
func Load ¶
Load loads configuration from the specified file path. If configPath is empty, it will attempt to discover a config file. Environment variable overrides are applied after loading the file.
func LoadAndValidate ¶
LoadAndValidate loads and validates configuration. Returns the config and any validation errors/warnings.
func LoadFromString ¶
LoadFromString parses configuration from a string with the specified format.
func LoadWithDefaults ¶
LoadWithDefaults returns a configuration with default values and environment variable overrides applied.
func MergeConfigs ¶
MergeConfigs merges override configuration into base configuration. The override values take precedence over base values. For nested objects, a deep merge is performed. Arrays replace by default (use *_append fields for appending).
func MergeSlice ¶
MergeSlice merges two slices with optional append behavior. If append is true, the override slice is appended to the base slice. Otherwise, the override slice replaces the base slice.
func MustLoad ¶
MustLoad loads configuration and panics on error. This is useful for initialization code where config loading failure should be fatal.
func ParseJSON ¶
ParseJSON parses JSON configuration data into a Config struct. The JSON data is expected to have a top-level "markata-go" key.
func ParseTOML ¶
ParseTOML parses TOML configuration data into a Config struct. The TOML data is expected to have a top-level [markata-go] section.
func ParseYAML ¶
ParseYAML parses YAML configuration data into a Config struct. The YAML data is expected to have a top-level markata-go key.
func SetEnvValue ¶
SetEnvValue sets an environment variable with the MARKATA_GO_ prefix. This is primarily useful for testing.
func SplitErrorsAndWarnings ¶
SplitErrorsAndWarnings separates errors and warnings into separate slices.
func StructToEnvKeys ¶
StructToEnvKeys returns a map of environment variable keys for a struct. This is useful for documentation and debugging.
func UnsetEnvValue ¶
UnsetEnvValue unsets an environment variable with the MARKATA_GO_ prefix. This is primarily useful for testing.
func ValidateAndWarn ¶
ValidateAndWarn validates config and logs warnings but only returns actual errors. This is useful when you want to proceed with warnings but stop on errors.
func ValidateConfig ¶
ValidateConfig validates a configuration and returns any errors or warnings. Errors are returned first, followed by warnings. The returned slice will be nil if no issues are found.
Types ¶
type Path ¶
type Path struct {
Path string // Full path to the config file
Format Format // Format of the config file
Source string // Where it was found: "cli", "cwd", "user"
}
Path holds the result of config file discovery with additional metadata.
func DiscoverAll ¶
func DiscoverAll() []Path
DiscoverAll finds all config files in the standard locations. This is useful for debugging or showing available configs.
type ValidationError ¶
type ValidationError struct {
Field string
Message string
IsWarn bool // If true, this is a warning rather than an error
}
ValidationError represents a configuration validation error.
func (ValidationError) Error ¶
func (e ValidationError) Error() string
Source Files