From 6f22ed3d7d2ed56a8486a5ce142a89f3c1d81bcb Mon Sep 17 00:00:00 2001 From: Pedro Torcatt Date: Sat, 7 Nov 2026 20:26:28 -0400 Subject: [PATCH 1/2] feat(config): expose a free-form extra table from site.toml - Add an `extra` mapping to `Config` and expose it to templates as `site.extra` - Reject non-table values with a ConfigError instead of failing later - Cover the new field with tests --- src/jamstack/config.py | 7 +++++++ tests/test_config.py | 17 +++++++++++++++++ 2 files changed, 24 insertions(+) diff --git a/src/jamstack/config.py b/src/jamstack/config.py index c8bab5e..c7b5e33 100644 --- a/src/jamstack/config.py +++ b/src/jamstack/config.py @@ -2,6 +2,7 @@ import tomllib from dataclasses import dataclass from pathlib import Path +from typing import Any THEME_NAME_PATTERN = re.compile(r"^[a-z0-9][a-z0-9_-]*$") @@ -24,6 +25,7 @@ class Config: language: str output: Path theme: str + extra: dict[str, Any] def load_config(root: Path) -> Config: @@ -39,6 +41,10 @@ def load_config(root: Path) -> Config: site = data.get("site", {}) build = data.get("build", {}) theme = data.get("theme", {}) + extra = data.get("extra", {}) + + if not isinstance(extra, dict): + raise ConfigError(f"{path}: [extra] must be a table") title = str(site.get("title", "")).strip() if not title: @@ -57,4 +63,5 @@ def load_config(root: Path) -> Config: language=str(site.get("language", "en")), output=root / str(build.get("output", "dist")), theme=theme_name, + extra=extra, ) diff --git a/tests/test_config.py b/tests/test_config.py index 74fd88b..8e295f4 100644 --- a/tests/test_config.py +++ b/tests/test_config.py @@ -18,6 +18,7 @@ def test_loads_defaults(tmp_path: Path) -> None: assert config.output == tmp_path / "dist" assert config.theme == "minimal" assert config.language == "en" + assert config.extra == {} def test_missing_file(tmp_path: Path) -> None: @@ -43,3 +44,19 @@ def test_custom_output(tmp_path: Path) -> None: write_config(tmp_path, '[site]\ntitle = "x"\n\n[build]\noutput = "public"\n') assert load_config(tmp_path).output == tmp_path / "public" + + +def test_extra_table_is_exposed(tmp_path: Path) -> None: + write_config( + tmp_path, + '[site]\ntitle = "x"\n\n[extra.footer]\ntext = "Hello"\n', + ) + + assert load_config(tmp_path).extra["footer"]["text"] == "Hello" + + +def test_extra_must_be_a_table(tmp_path: Path) -> None: + write_config(tmp_path, 'extra = "nope"\n\n[site]\ntitle = "x"\n') + + with pytest.raises(ConfigError, match="extra"): + load_config(tmp_path) From c8b593fd863695ffbafbe4558f7c55aac81eaa90 Mon Sep 17 00:00:00 2001 From: Pedro Torcatt Date: Sat, 7 Nov 2026 20:26:29 -0400 Subject: [PATCH 2/2] docs: document the extra table - Describe `[extra]`, its type constraint and the StrictUndefined lookup pattern for optional keys --- docs/configuration.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/configuration.md b/docs/configuration.md index aa39e83..9cbe2e7 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -68,6 +68,23 @@ The name must match `^[a-z0-9][a-z0-9_-]*$`. Jamstack resolves it from `/themes//` first and falls back to the themes bundled with the package. See [Themes](themes.md). +## `[extra]` + +Free-form table for values your theme needs. Jamstack does not interpret it: +templates read it as `site.extra`. + +```toml +[extra] +footer_text = "Built with jamstack" + +[extra.social] +github = "https://github.com/jamstackpy" +``` + +It must be a table; any other type stops the build with an error. Themes render +with `StrictUndefined`, so read optional keys with `site.extra.get("...")` +instead of `site.extra.key`. + ## Behaviour worth knowing - Unknown keys are ignored, so a future version can add options without