Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,23 @@ The name must match `^[a-z0-9][a-z0-9_-]*$`. Jamstack resolves it from
`<project>/themes/<name>/` 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
Expand Down
7 changes: 7 additions & 0 deletions src/jamstack/config.py
Original file line number Diff line number Diff line change
Expand Up @@ -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_-]*$")

Expand All @@ -24,6 +25,7 @@ class Config:
language: str
output: Path
theme: str
extra: dict[str, Any]


def load_config(root: Path) -> Config:
Expand All @@ -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:
Expand All @@ -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,
)
17 changes: 17 additions & 0 deletions tests/test_config.py
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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)