Module: Abqari::SiteConfig

Defined in:

lib/abqari/site_config.rb

Overview

Lightweight schema check for config/site.yml. The goal is not full schema validation — yagni for a single-author tool — but to catch the typo class of bug:

manifest:
theme_colour: '#000'    # 🐛 should be `theme_color`

…which silently no-ops and leaves the operator wondering why their PWA install icon doesn't pick up the brand colour.

Strategy: known top-level keys are allow-listed below. Unknown keys warn by default (so existing sites don't break on upgrade), and raise when ABQARI_STRICT_CONFIG=true. CI workflows that want the gate enforced flip the env var. The plan is to flip the default to raise once the warn-mode period has passed.

Reserved keys we tolerate without warning:

- `environments` is structural (per-env overrides).
- Anything beginning with `x_` is treated as a user extension
namespace, mirroring HTTP/MIME conventions. Lets a consuming
site park its own metadata in the same file without false-
positive warnings.

Constant Summary

DEFAULTS =

Static defaults applied to every site. User values in config/site.yml deep-merge over these — any user-set key wins. Only static defaults belong here; dynamic ones (minify = env == :production) stay in their callers.

Adding a default here removes a config.fetch('key', value) call elsewhere — one auditable place for the defaults the engine assumes, instead of scattered ternaries.

{
  'indexable'           => true,
  'block_ai_scraping'   => true,
  'syntax_highlighting' => true,
  'erb_in_markdown'     => false,
  'theme_toggle'        => true,
  # The default here (not buried in AssetPipeline) so EVERY reader
  # of config['theme'] agrees. When it lived pipeline-side, a site
  # with no `theme:` key built the minimal theme but the renderer's
  # theme-mtime scoping read '' — so theme CSS edits rebuilt assets
  # without re-rendering pages, and hot reload served stale hrefs.
  'theme'               => 'minimal'
}.freeze

KNOWN_KEYS =

Every top-level key the engine reads anywhere (rb + erb). Keep in lockstep with the readers — when adding a new top-level config key, add it here too. CI's audit catches drift.

%w[
  author
  block_ai_scraping
  bundle_assets
  collections
  contact
  csp
  deploy
  description
  drafts
  environments
  erb_in_markdown
  folio
  fonts
  fonts_preload
  footer
  headers
  home
  icons
  images
  indexable
  indieweb
  llms
  locale
  manifest
  media
  minify
  nav
  newsletter
  og_images
  og_locale
  pagination
  plausible
  robots_disallow
  search
  security_contact
  share_image
  social
  speculation_rules
  syndication
  syntax_highlighting
  syntax_theme
  syntax_theme_dark
  taxonomies
  theme
  theme_toggle
  timezone
  title
  twitter
  url
  validate
  visualizations
].freeze

Class Method Summary

• .deep_merge(base, override) ⇒ Object
• .validate!(config, strict: nil, env: nil) ⇒ Object
• .validate_required!(config, strict:, env:) ⇒ Object

  Keys that must be present for a correct build.

• .validate_url_has_no_path!(url) ⇒ Object

  Abqari emits root-relative asset and internal-link URLs (/assets/…, /posts/…, /feed.xml), so a url: with a path component (https://user.github.io/repo) produces a site whose every asset and link 404s under the prefix.

• .with_defaults(config) ⇒ Object

  Deep-merge DEFAULTS under the user's config.

Class Method Details

.deep_merge(base, override) ⇒ Object

# File 'lib/abqari/site_config.rb', line 118

def deep_merge(base, override)
  base.merge(override) do |_, b, o|
    b.is_a?(Hash) && o.is_a?(Hash) ? deep_merge(b, o) : o
  end
end

.validate!(config, strict: nil, env: nil) ⇒ Object

# File 'lib/abqari/site_config.rb', line 124

def validate!(config, strict: nil, env: nil)
  strict = ENV['ABQARI_STRICT_CONFIG'] == 'true' if strict.nil?

  validate_required!(config, strict: strict, env: env)

  unknown = config.keys.map(&:to_s).reject do |key|
    KNOWN_KEYS.include?(key) || key.start_with?('x_')
  end

  return if unknown.empty?

  # The advice differs by mode. The old message ended "…or set
  # ABQARI_STRICT_CONFIG=true to make this a hard error" in BOTH
  # branches — including the one raised *because* it was already set,
  # which told the user to enable the thing that had just fired.
  base = "Unknown config key(s) in site.yml: #{unknown.sort.join(', ')}. " \
         'Typos silently no-op; add an `x_` prefix for intentional user extensions'

  if strict
    raise UserError, "#{base} (ABQARI_STRICT_CONFIG is on, so this is fatal)."
  end

  Log.warn "#{base}, or set ABQARI_STRICT_CONFIG=true to make this a hard error."
end

.validate_required!(config, strict:, env:) ⇒ Object

Keys that must be present for a correct build. title feeds