jamstack 2.0.0rc1__py3-none-any.whl

jamstack/__about__.py

@@ -0,0 +1 @@
+__version__ = "2.0.0rc1"

jamstack/__init__.py

@@ -0,0 +1,3 @@
+from jamstack.__about__ import __version__
+
+__all__ = ["__version__"]

jamstack/__main__.py

@@ -0,0 +1,4 @@
+from jamstack.cli import main
+
+if __name__ == "__main__":
+    main()

jamstack/builder.py

@@ -0,0 +1,70 @@
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+from jinja2 import Environment, TemplateNotFound
+from markupsafe import Markup
+
+from jamstack.config import Config
+from jamstack.content import Page, load_pages, render_markdown
+from jamstack.feed import write_feed, write_sitemap
+from jamstack.render import create_environment
+from jamstack.theme import resolve_theme
+
+
+@dataclass(frozen=True)
+class BuildResult:
+    output: Path
+    page_count: int
+
+
+def build(config: Config, *, clean: bool = False, drafts: bool = False) -> BuildResult:
+    theme = resolve_theme(config.theme, config.root)
+
+    template_dirs = [path for path in (config.root / "templates", theme.templates) if path.is_dir()]
+    environment = create_environment(template_dirs)
+
+    pages = load_pages(config.root / "content", drafts=drafts)
+
+    if clean and config.output.exists():
+        shutil.rmtree(config.output)
+    config.output.mkdir(parents=True, exist_ok=True)
+
+    for page in pages:
+        context = {"site": config, "page": page, "pages": pages}
+        page.content = render_page_body(environment, page, context)
+        html = environment.get_template(page.template).render(context)
+        destination = config.output / page.output
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        destination.write_text(html, encoding="utf-8")
+
+    copy_static(theme.static, config.output)
+    copy_static(config.root / "static", config.output)
+    write_sitemap(config, pages, config.output)
+    write_feed(config, pages, config.output)
+    render_not_found(environment, config, pages, config.output)
+
+    return BuildResult(output=config.output, page_count=len(pages))
+
+
+def render_not_found(
+    environment: Environment, config: Config, pages: list[Page], output: Path
+) -> None:
+    try:
+        template = environment.get_template("404.html")
+    except TemplateNotFound:
+        return
+
+    destination = output / "404.html"
+    destination.write_text(template.render(site=config, pages=pages), encoding="utf-8")
+
+
+def render_page_body(environment: Environment, page: Page, context: dict[str, object]) -> Markup:
+    if page.source.suffix == ".html":
+        return Markup(environment.from_string(page.body).render(context))
+    return render_markdown(page.body)
+
+
+def copy_static(source: Path, destination: Path) -> None:
+    if source.is_dir():
+        shutil.copytree(source, destination, dirs_exist_ok=True)

jamstack/cli.py

@@ -0,0 +1,113 @@
+import json
+import shutil
+from pathlib import Path
+
+import click
+
+from jamstack.__about__ import __version__
+from jamstack.builder import build as build_site
+from jamstack.config import JamstackError, load_config
+from jamstack.server import serve as serve_site
+from jamstack.theme import discover_themes, resolve_theme
+
+INDEX_PAGE = """+++
+title = "Welcome"
++++
+
+This is your new site. Edit `content/index.md` and run `jamstack build`.
+"""
+
+
+@click.group()
+@click.version_option(__version__, prog_name="jamstack")
+def main() -> None:
+    """Static site generator built on Python and Jinja."""
+
+
+@main.command()
+@click.argument("path", default=".", type=click.Path(path_type=Path))
+@click.option(
+    "--theme", default="minimal", show_default=True, help="Theme to scaffold the site with."
+)
+@click.option("--force", is_flag=True, help="Write into a non-empty directory.")
+def init(path: Path, theme: str, force: bool) -> None:
+    """Create a new site."""
+    if path.is_file():
+        raise click.ClickException(f"{path} is a file, not a directory")
+
+    if path.is_dir() and any(path.iterdir()) and not force:
+        raise click.ClickException(f"{path} is not empty. Use --force to write anyway.")
+
+    selected = resolve_theme(theme, path)
+
+    site_toml = f"""[site]
+title = {json.dumps(path.resolve().name.replace("-", " ").replace("_", " ").title())}
+description = ""
+# Absolute public URL. Required to generate sitemap.xml and feed.xml.
+base_url = ""
+language = "en"
+
+[build]
+output = "dist"
+
+[theme]
+name = {json.dumps(theme)}
+"""
+
+    if selected.scaffold:
+        shutil.copytree(selected.scaffold, path, dirs_exist_ok=True)
+
+    files = {
+        "site.toml": site_toml,
+        "content/index.md": INDEX_PAGE,
+        ".gitignore": "dist/\n",
+    }
+    for relative, content in files.items():
+        destination = path / relative
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        destination.write_text(content, encoding="utf-8")
+
+    click.echo(f"Created site in {path} using the {theme!r} theme")
+    click.echo("Next steps:")
+    click.echo(f"  cd {path}")
+    click.echo("  jamstack build")
+
+
+@main.command()
+@click.option("--clean", is_flag=True, help="Delete the output directory before building.")
+@click.option("--drafts", is_flag=True, help="Include pages marked as drafts.")
+def build(clean: bool, drafts: bool) -> None:
+    """Build the site into the output directory."""
+    try:
+        config = load_config(Path.cwd())
+        result = build_site(config, clean=clean, drafts=drafts)
+    except JamstackError as error:
+        raise click.ClickException(str(error)) from error
+
+    click.echo(f"Built {result.page_count} page(s) into {result.output}")
+
+
+@main.command()
+@click.option("--port", default=8000, show_default=True, type=click.IntRange(0, 65535))
+@click.option("--drafts", is_flag=True, help="Include pages marked as drafts.")
+def serve(port: int, drafts: bool) -> None:
+    """Build the site, serve it, and rebuild on changes."""
+    try:
+        config = load_config(Path.cwd())
+        serve_site(config, port=port, drafts=drafts)
+    except JamstackError as error:
+        raise click.ClickException(str(error)) from error
+
+
+@main.command("themes")
+def list_themes() -> None:
+    """List the available themes."""
+    try:
+        themes = discover_themes(Path.cwd())
+    except JamstackError as error:
+        raise click.ClickException(str(error)) from error
+
+    width = max(len(theme.name) for theme in themes)
+    for theme in themes:
+        origin = "bundled" if theme.bundled else "local"
+        click.echo(f"{theme.name:<{width}}  {origin:<7}  {theme.description}")

jamstack/config.py

@@ -0,0 +1,60 @@
+import re
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+THEME_NAME_PATTERN = re.compile(r"^[a-z0-9][a-z0-9_-]*$")
+
+
+class JamstackError(Exception):
+    """Base class for expected, user-facing failures."""
+
+
+class ConfigError(JamstackError):
+    """Raised when site.toml is missing or invalid."""
+
+
+@dataclass(frozen=True)
+class Config:
+    root: Path
+    title: str
+    description: str
+    author: str
+    base_url: str
+    language: str
+    output: Path
+    theme: str
+
+
+def load_config(root: Path) -> Config:
+    path = root / "site.toml"
+    if not path.is_file():
+        raise ConfigError(f"{path} not found. Run 'jamstack init' first.")
+
+    try:
+        data = tomllib.loads(path.read_text(encoding="utf-8"))
+    except tomllib.TOMLDecodeError as error:
+        raise ConfigError(f"{path}: {error}") from error
+
+    site = data.get("site", {})
+    build = data.get("build", {})
+    theme = data.get("theme", {})
+
+    title = str(site.get("title", "")).strip()
+    if not title:
+        raise ConfigError(f"{path}: [site].title is required")
+
+    theme_name = str(theme.get("name", "minimal"))
+    if not THEME_NAME_PATTERN.fullmatch(theme_name):
+        raise ConfigError(f"{path}: invalid theme name {theme_name!r}")
+
+    return Config(
+        root=root,
+        title=title,
+        description=str(site.get("description", "")),
+        author=str(site.get("author", "")),
+        base_url=str(site.get("base_url", "")),
+        language=str(site.get("language", "en")),
+        output=root / str(build.get("output", "dist")),
+        theme=theme_name,
+    )

jamstack/content.py

@@ -0,0 +1,131 @@
+import tomllib
+from dataclasses import dataclass, field
+from datetime import date, datetime
+from pathlib import Path
+from typing import Any
+
+from markdown_it import MarkdownIt
+from markupsafe import Markup
+
+from jamstack.config import JamstackError
+
+FRONT_MATTER_DELIMITER = "+++"
+MARKDOWN = MarkdownIt("commonmark", {"html": True})
+
+
+class ContentError(JamstackError):
+    """Raised when a content file cannot be parsed."""
+
+
+@dataclass
+class Page:
+    source: Path
+    url: str
+    output: Path
+    title: str
+    template: str
+    date: date | None
+    draft: bool
+    body: str
+    meta: dict[str, Any] = field(default_factory=dict)
+    content: Markup = field(default_factory=Markup)
+
+
+def load_pages(content_dir: Path, *, drafts: bool = False) -> list[Page]:
+    if not content_dir.is_dir():
+        return []
+
+    sources = sorted(
+        path
+        for path in content_dir.rglob("*")
+        if path.is_file() and path.suffix in {".md", ".html"}
+    )
+
+    pages: list[Page] = []
+    seen_outputs: dict[Path, Path] = {}
+    for source in sources:
+        page = load_page(source, content_dir)
+        if page.draft and not drafts:
+            continue
+        if page.output in seen_outputs:
+            raise ContentError(
+                f"{source} and {seen_outputs[page.output]} both build to {page.output}"
+            )
+        seen_outputs[page.output] = source
+        pages.append(page)
+
+    pages.sort(key=lambda page: page.title.lower())
+    pages.sort(key=lambda page: page.date or date.min, reverse=True)
+    return pages
+
+
+def load_page(source: Path, content_dir: Path) -> Page:
+    text = source.read_text(encoding="utf-8")
+    meta, body = split_front_matter(text, source)
+
+    relative = source.relative_to(content_dir).with_suffix("")
+    parts = list(relative.parts)
+    if parts[-1] == "index":
+        parts.pop()
+
+    return Page(
+        source=source,
+        url="/" + "".join(f"{part}/" for part in parts) if parts else "/",
+        output=Path(*parts, "index.html"),
+        title=parse_title(meta, relative.name),
+        template=parse_template(meta, relative.name),
+        date=parse_date(meta.get("date"), source),
+        draft=bool(meta.get("draft", False)),
+        body=body,
+        meta=meta,
+    )
+
+
+def split_front_matter(text: str, source: Path) -> tuple[dict[str, Any], str]:
+    lines = text.splitlines(keepends=True)
+    if not lines or lines[0].strip() != FRONT_MATTER_DELIMITER:
+        return {}, text
+
+    for index in range(1, len(lines)):
+        if lines[index].strip() != FRONT_MATTER_DELIMITER:
+            continue
+
+        raw = "".join(lines[1:index])
+        body = "".join(lines[index + 1 :]).lstrip("\n")
+        try:
+            return tomllib.loads(raw), body
+        except tomllib.TOMLDecodeError as error:
+            raise ContentError(f"{source}: invalid front matter: {error}") from error
+
+    raise ContentError(f"{source}: unterminated front matter")
+
+
+def parse_title(meta: dict[str, Any], stem: str) -> str:
+    title = str(meta.get("title", "")).strip()
+    return title or stem.replace("-", " ").replace("_", " ").title()
+
+
+def parse_template(meta: dict[str, Any], stem: str) -> str:
+    template = str(meta.get("template", "")).strip()
+    if not template:
+        template = "index" if stem == "index" else "page"
+    return template if Path(template).suffix else f"{template}.html"
+
+
+def parse_date(value: Any, source: Path) -> date | None:
+    if value is None:
+        return None
+    if isinstance(value, datetime):
+        return value.date()
+    if isinstance(value, date):
+        return value
+    if isinstance(value, str):
+        try:
+            return date.fromisoformat(value)
+        except ValueError as error:
+            raise ContentError(f"{source}: invalid date {value!r}") from error
+    raise ContentError(f"{source}: date must be an ISO date, got {value!r}")
+
+
+def render_markdown(body: str) -> Markup:
+    return Markup(MARKDOWN.render(body))

jamstack/feed.py

@@ -0,0 +1,75 @@
+from datetime import UTC, date, datetime, time
+from pathlib import Path
+from xml.etree import ElementTree
+
+from jamstack.config import Config
+from jamstack.content import Page
+
+ATOM_NAMESPACE = "http://www.w3.org/2005/Atom"
+SITEMAP_NAMESPACE = "http://www.sitemaps.org/schemas/sitemap/0.9"
+
+
+def write_sitemap(config: Config, pages: list[Page], output: Path) -> Path | None:
+    if not config.base_url or not pages:
+        return None
+
+    root = ElementTree.Element("urlset", xmlns=SITEMAP_NAMESPACE)
+    for page in pages:
+        url = ElementTree.SubElement(root, "url")
+        ElementTree.SubElement(url, "loc").text = absolute_url(config, page.url)
+        if page.date:
+            ElementTree.SubElement(url, "lastmod").text = page.date.isoformat()
+
+    return _write(root, output / "sitemap.xml")
+
+
+def write_feed(config: Config, pages: list[Page], output: Path) -> Path | None:
+    entries = [page for page in pages if page.date is not None]
+    if not config.base_url or not entries:
+        return None
+
+    site_url = absolute_url(config, "/")
+    root = ElementTree.Element("feed", xmlns=ATOM_NAMESPACE, lang=config.language)
+    ElementTree.SubElement(root, "title").text = config.title
+    if config.description:
+        ElementTree.SubElement(root, "subtitle").text = config.description
+    ElementTree.SubElement(root, "link", href=site_url, rel="alternate")
+    ElementTree.SubElement(root, "link", href=absolute_url(config, "/feed.xml"), rel="self")
+    ElementTree.SubElement(root, "id").text = site_url
+    ElementTree.SubElement(root, "updated").text = _timestamp(
+        max(page.date for page in entries if page.date)
+    )
+    author = ElementTree.SubElement(root, "author")
+    ElementTree.SubElement(author, "name").text = config.author or config.title
+
+    for page in entries:
+        url = absolute_url(config, page.url)
+        entry = ElementTree.SubElement(root, "entry")
+        ElementTree.SubElement(entry, "title").text = page.title
+        ElementTree.SubElement(entry, "link", href=url)
+        ElementTree.SubElement(entry, "id").text = url
+        ElementTree.SubElement(entry, "updated").text = _timestamp(page.date)
+        summary = str(page.meta.get("summary", "")).strip()
+        if summary:
+            ElementTree.SubElement(entry, "summary").text = summary
+        content = ElementTree.SubElement(entry, "content", type="html")
+        content.text = str(page.content)
+
+    return _write(root, output / "feed.xml")
+
+
+def absolute_url(config: Config, path: str) -> str:
+    return config.base_url.rstrip("/") + path
+
+
+def _timestamp(value: date) -> str:
+    return datetime.combine(value, time.min, tzinfo=UTC).isoformat()
+
+
+def _write(root: ElementTree.Element, destination: Path) -> Path:
+    ElementTree.indent(root, space="  ")
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    destination.write_bytes(
+        ElementTree.tostring(root, encoding="utf-8", xml_declaration=True) + b"\n"
+    )
+    return destination

jamstack/render.py

@@ -0,0 +1,12 @@
+from pathlib import Path
+
+from jinja2 import Environment, FileSystemLoader, StrictUndefined, select_autoescape
+
+
+def create_environment(template_dirs: list[Path]) -> Environment:
+    return Environment(
+        loader=FileSystemLoader([str(path) for path in template_dirs]),
+        autoescape=select_autoescape(["html", "xml"]),
+        undefined=StrictUndefined,
+        keep_trailing_newline=True,
+    )

jamstack/server.py

@@ -0,0 +1,92 @@
+import functools
+import threading
+from collections.abc import Iterable
+from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+
+from jamstack.builder import build
+from jamstack.config import Config
+from jamstack.theme import resolve_theme
+
+
+class _QuietHandler(SimpleHTTPRequestHandler):
+    def log_message(self, format: str, *args: object) -> None:
+        pass
+
+
+def create_server(config: Config, port: int = 8000) -> ThreadingHTTPServer:
+    handler = functools.partial(_QuietHandler, directory=str(config.output.resolve()))
+    return ThreadingHTTPServer(("127.0.0.1", port), handler)
+
+
+def watched_paths(config: Config) -> list[Path]:
+    theme = resolve_theme(config.theme, config.root)
+    return [
+        config.root / "site.toml",
+        config.root / "content",
+        config.root / "templates",
+        config.root / "static",
+        theme.templates,
+        theme.static,
+    ]
+
+
+def snapshot(paths: Iterable[Path]) -> dict[str, tuple[int, int]]:
+    state: dict[str, tuple[int, int]] = {}
+    for path in paths:
+        if path.is_file():
+            files: Iterable[Path] = [path]
+        elif path.is_dir():
+            files = path.rglob("*")
+        else:
+            continue
+        for file in files:
+            if file.is_file():
+                stat = file.stat()
+                state[str(file)] = (stat.st_mtime_ns, stat.st_size)
+    return state
+
+
+def watch(config: Config, drafts: bool, poll_interval: float, stop: threading.Event) -> None:
+    paths = watched_paths(config)
+    previous = snapshot(paths)
+    while not stop.wait(poll_interval):
+        current = snapshot(paths)
+        if current == previous:
+            continue
+        stop.wait(poll_interval)  # let editors finish writing
+        settled = snapshot(paths)
+        if settled != current:
+            continue
+        previous = settled
+        try:
+            result = build(config, drafts=drafts)
+        except Exception as error:  # a bad build must not kill the watcher
+            print(f"Build failed: {error}", flush=True)
+        else:
+            print(f"Rebuilt {result.page_count} page(s)", flush=True)
+
+
+def serve(
+    config: Config, port: int = 8000, drafts: bool = False, poll_interval: float = 0.5
+) -> None:
+    result = build(config, drafts=drafts)
+    print(f"Built {result.page_count} page(s) into {result.output}", flush=True)
+
+    server = create_server(config, port)
+    address, actual_port = server.server_address[:2]
+    print(f"Serving at http://{address}:{actual_port}/ (Ctrl+C to stop)", flush=True)
+
+    stop = threading.Event()
+    watcher = threading.Thread(
+        target=watch, args=(config, drafts, poll_interval, stop), daemon=True
+    )
+    watcher.start()
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        stop.set()
+        server.server_close()
+        watcher.join(timeout=5)

jamstack/theme.py

@@ -0,0 +1,84 @@
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+from jamstack.config import JamstackError
+
+PACKAGED_THEMES = Path(__file__).parent / "themes"
+
+
+class ThemeError(JamstackError):
+    """Raised when a theme cannot be resolved or is malformed."""
+
+
+@dataclass(frozen=True)
+class Theme:
+    name: str
+    description: str
+    root: Path
+    templates: Path
+    static: Path
+    scaffold: Path | None
+    bundled: bool
+
+
+def load_theme(root: Path, *, bundled: bool) -> Theme:
+    manifest = root / "theme.toml"
+    if not manifest.is_file():
+        raise ThemeError(f"{root} is not a theme: theme.toml is missing")
+
+    try:
+        data = tomllib.loads(manifest.read_text(encoding="utf-8"))
+    except tomllib.TOMLDecodeError as error:
+        raise ThemeError(f"{manifest}: {error}") from error
+
+    name = str(data.get("name", "")).strip()
+    if not name:
+        raise ThemeError(f"{manifest}: name is required")
+    if name != root.name:
+        raise ThemeError(f"{manifest}: name {name!r} does not match directory {root.name!r}")
+
+    templates = root / "templates"
+    if not templates.is_dir():
+        raise ThemeError(f"{manifest}: templates directory is missing")
+
+    scaffold = root / "scaffold"
+    return Theme(
+        name=name,
+        description=str(data.get("description", "")).strip(),
+        root=root,
+        templates=templates,
+        static=root / "static",
+        scaffold=scaffold if scaffold.is_dir() else None,
+        bundled=bundled,
+    )
+
+
+def resolve_theme(name: str, project_root: Path) -> Theme:
+    candidates = (
+        (project_root / "themes" / name, False),
+        (PACKAGED_THEMES / name, True),
+    )
+    for root, bundled in candidates:
+        if root.is_dir():
+            return load_theme(root, bundled=bundled)
+
+    available = ", ".join(theme.name for theme in discover_themes(project_root))
+    raise ThemeError(f"Theme {name!r} not found. Available themes: {available or 'none'}")
+
+
+def discover_themes(project_root: Path) -> list[Theme]:
+    themes: dict[str, Theme] = {}
+    for root in sorted(PACKAGED_THEMES.iterdir()):
+        if root.is_dir():
+            theme = load_theme(root, bundled=True)
+            themes[theme.name] = theme
+
+    local_root = project_root / "themes"
+    if local_root.is_dir():
+        for root in sorted(local_root.iterdir()):
+            if root.is_dir():
+                theme = load_theme(root, bundled=False)
+                themes[theme.name] = theme
+
+    return sorted(themes.values(), key=lambda theme: theme.name)

jamstack/themes/blog/scaffold/content/posts/hello-world.md

@@ -0,0 +1,9 @@
++++
+title = "Hello, world"
+date = 2026-11-06
+template = "post"
+summary = "The first post on your new site."
++++
+
+This is your first post. Edit `content/posts/hello-world.md` and run
+`jamstack build` to see the changes.