ogcards 0.1.0__tar.gz

ogcards-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync
+      - run: uv run ruff check .
+      - run: uv run mypy
+      - run: uv run pytest -q

ogcards-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: Publish
+
+# Publishes to PyPI on a version tag via Trusted Publishing (OIDC).
+# No API token is stored: register this repo + workflow as a trusted
+# publisher on the PyPI project, and set a "pypi" environment.
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

ogcards-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Local render output
+*.png
+!examples/**/*.png
+.ogcards-cache.json

ogcards-0.1.0/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+This project adheres to [Common Changelog](https://common-changelog.org) and
+[Semantic Versioning](https://semver.org).
+
+## [0.1.0] - 2026-06-14
+
+_Initial release._
+
+### Added
+
+- Add `build`, `preview`, and `init` CLI commands
+- Add a TOML theme with named templates and a JSON card manifest
+- Add a Pillow `stack` layout with title auto-fit, wrapping, and ellipsis
+- Add incremental rendering via a content-fingerprint cache
+- Add custom layout registration through `ogcards.templates.register`
+- Bundle the Inter typeface (SIL OFL 1.1) with a system-font fallback
+
+[0.1.0]: https://github.com/laplacef/ogcards/releases/tag/v0.1.0

ogcards-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Francisco Laplace
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ogcards-0.1.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: ogcards
+Version: 0.1.0
+Summary: Build-time Open Graph card generator for any static site. Manifest in, PNGs out, one dependency.
+Project-URL: Homepage, https://github.com/laplacef/ogcards
+Project-URL: Source, https://github.com/laplacef/ogcards
+Project-URL: Issues, https://github.com/laplacef/ogcards/issues
+Author: Francisco Laplace
+License-Expression: MIT
+License-File: LICENSE
+License-File: src/ogcards/fonts/OFL.txt
+Keywords: og-image,open-graph,pillow,social-card,ssg,static-site
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pillow>=10.0
+Description-Content-Type: text/markdown
+
+# ogcards
+
+Generate Open Graph cards for a static site at build time. Give it a JSON
+manifest and a TOML theme, and it writes one PNG per card with Pillow. No
+headless browser, no Node, no system libraries, just Pillow.
+
+It's framework-agnostic, so any generator that can write a JSON file can drive it.
+
+## Install
+
+```sh
+uv tool install ogcards
+```
+
+## Usage
+
+```sh
+ogcards init                # writes a sample ogcards.toml and og-manifest.json
+ogcards build --config ogcards.toml --manifest og-manifest.json --out-dir _site
+ogcards preview --title "Hello" --subtitle "June 2026" --out card.png
+```
+
+`build` is incremental, so a card re-renders only when its title, subtitle,
+template, or theme changes. Pass `--force` to rebuild everything.
+
+## Inputs
+
+Two files. The theme (`ogcards.toml`) is your branding. The manifest
+(`og-manifest.json`) is the per-build content your generator emits.
+
+```toml
+[canvas]
+width = 1200
+height = 630
+background = "#ffffff"
+
+[templates.post]
+title_size = 64       # shrinks automatically past max_title_lines
+title_color = "#1a1a1a"
+meta_color = "#535358"
+accent = "#0645ad"
+padding = 80
+max_title_lines = 3
+```
+
+```json
+{
+  "cards": [
+    {
+      "title": "Your Post Title",
+      "subtitle": "June 11, 2026",
+      "out": "assets/og/posts/your-post.png"
+    }
+  ]
+}
+```
+
+`out` is relative to `--out-dir`, and a card's `template` defaults to `post`.
+
+## Static sites
+
+Have your generator write `og-manifest.json` at build time, run `ogcards build`, 
+then point each `og:image` at the `out` path. See [`examples/jekyll/`](examples/jekyll/) 
+for a Jekyll manifest; the pattern is the same for Hugo or Eleventy.
+
+## License
+
+MIT. See [`LICENSE`](LICENSE).

ogcards-0.1.0/README.md

@@ -0,0 +1,68 @@
+# ogcards
+
+Generate Open Graph cards for a static site at build time. Give it a JSON
+manifest and a TOML theme, and it writes one PNG per card with Pillow. No
+headless browser, no Node, no system libraries, just Pillow.
+
+It's framework-agnostic, so any generator that can write a JSON file can drive it.
+
+## Install
+
+```sh
+uv tool install ogcards
+```
+
+## Usage
+
+```sh
+ogcards init                # writes a sample ogcards.toml and og-manifest.json
+ogcards build --config ogcards.toml --manifest og-manifest.json --out-dir _site
+ogcards preview --title "Hello" --subtitle "June 2026" --out card.png
+```
+
+`build` is incremental, so a card re-renders only when its title, subtitle,
+template, or theme changes. Pass `--force` to rebuild everything.
+
+## Inputs
+
+Two files. The theme (`ogcards.toml`) is your branding. The manifest
+(`og-manifest.json`) is the per-build content your generator emits.
+
+```toml
+[canvas]
+width = 1200
+height = 630
+background = "#ffffff"
+
+[templates.post]
+title_size = 64       # shrinks automatically past max_title_lines
+title_color = "#1a1a1a"
+meta_color = "#535358"
+accent = "#0645ad"
+padding = 80
+max_title_lines = 3
+```
+
+```json
+{
+  "cards": [
+    {
+      "title": "Your Post Title",
+      "subtitle": "June 11, 2026",
+      "out": "assets/og/posts/your-post.png"
+    }
+  ]
+}
+```
+
+`out` is relative to `--out-dir`, and a card's `template` defaults to `post`.
+
+## Static sites
+
+Have your generator write `og-manifest.json` at build time, run `ogcards build`, 
+then point each `og:image` at the `out` path. See [`examples/jekyll/`](examples/jekyll/) 
+for a Jekyll manifest; the pattern is the same for Hugo or Eleventy.
+
+## License
+
+MIT. See [`LICENSE`](LICENSE).

ogcards-0.1.0/examples/jekyll/og-manifest.json

@@ -0,0 +1,24 @@
+---
+# Place this file at your Jekyll site root. Jekyll renders it to
+# _site/og-manifest.json at build time (the front-matter block below is what
+# makes Jekyll process it). Then, as a post-build CI step:
+#
+#   ogcards build --config ogcards.toml \
+#                  --manifest _site/og-manifest.json \
+#                  --out-dir _site
+#
+# Point your og:image meta tag at the same path, e.g.
+#   /assets/og/posts/{{ page.slug }}.png
+---
+{
+  "cards": [
+    {%- for post in site.posts %}
+    {
+      "title": {{ post.title | jsonify }},
+      "subtitle": "{{ post.date | date: '%B %-d, %Y' }}",
+      "template": "post",
+      "out": "assets/og/posts/{{ post.slug }}.png"
+    }{%- unless forloop.last %},{%- endunless %}
+    {%- endfor %}
+  ]
+}

ogcards-0.1.0/examples/og-manifest.json

@@ -0,0 +1,22 @@
+{
+  "cards": [
+    {
+      "title": "Effectively Communicating with Non-Technical Stakeholders",
+      "subtitle": "June 11, 2026",
+      "template": "post",
+      "out": "assets/og/posts/communicating-with-stakeholders.png"
+    },
+    {
+      "title": "Short Title",
+      "subtitle": "June 13, 2026",
+      "template": "post",
+      "out": "assets/og/posts/short.png"
+    },
+    {
+      "title": "A Very Long Title That Should Exercise the Auto-Fit and Wrapping Logic Across Several Lines and Eventually Force an Ellipsis When It Runs Out of Room",
+      "subtitle": "June 1, 2026",
+      "template": "post",
+      "out": "assets/og/posts/long.png"
+    }
+  ]
+}

ogcards-0.1.0/examples/ogcards.toml

@@ -0,0 +1,13 @@
+[canvas]
+width = 1200
+height = 630
+background = "#ffffff"
+
+[templates.post]
+title_size = 64
+title_color = "#1a1a1a"
+meta_size = 28
+meta_color = "#535358"
+accent = "#0645ad"
+padding = 80
+max_title_lines = 3

ogcards-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ogcards"
+version = "0.1.0"
+description = "Build-time Open Graph card generator for any static site. Manifest in, PNGs out, one dependency."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE", "src/ogcards/fonts/OFL.txt"]
+authors = [{ name = "Francisco Laplace" }]
+keywords = ["open-graph", "og-image", "social-card", "static-site", "pillow", "ssg"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia :: Graphics",
+    "Topic :: Software Development :: Build Tools",
+    "Typing :: Typed",
+]
+dependencies = ["pillow>=10.0"]
+
+[project.urls]
+Homepage = "https://github.com/laplacef/ogcards"
+Source = "https://github.com/laplacef/ogcards"
+Issues = "https://github.com/laplacef/ogcards/issues"
+
+[project.scripts]
+ogcards = "ogcards.cli:main"
+
+[dependency-groups]
+dev = ["pytest>=8", "ruff>=0.6", "mypy>=1.11"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ogcards"]
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.mypy]
+strict = true
+files = ["src", "tests"]

ogcards-0.1.0/src/ogcards/__init__.py

@@ -0,0 +1,17 @@
+"""ogcards — build-time Open Graph card generator for any static site."""
+
+from __future__ import annotations
+
+from ogcards.config import Theme, load_theme
+from ogcards.manifest import Card, Manifest, load_manifest
+from ogcards.render import render_card
+
+__all__ = [
+    "Card",
+    "Manifest",
+    "Theme",
+    "load_manifest",
+    "load_theme",
+    "render_card",
+]
+__version__ = "0.1.0"

ogcards-0.1.0/src/ogcards/cache.py

@@ -0,0 +1,42 @@
+"""Incremental rendering: a card is re-rendered only when its inputs change.
+
+The fingerprint folds in the card, its resolved template, and a theme token so
+that a branding tweak (canvas size, fonts) invalidates every card.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import asdict
+from pathlib import Path
+
+from ogcards.config import Template
+from ogcards.manifest import Card
+
+
+def fingerprint(card: Card, template: Template, theme_token: str) -> str:
+    """Return a stable hash of everything that affects a card's pixels."""
+    payload = json.dumps(
+        {"card": asdict(card), "template": asdict(template), "theme": theme_token},
+        sort_keys=True,
+    )
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+def load_cache(path: Path) -> dict[str, str]:
+    """Read the out-path -> fingerprint map, or an empty map if absent/corrupt."""
+    if not path.is_file():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        return {}
+    if not isinstance(data, dict):
+        return {}
+    return {str(k): str(v) for k, v in data.items()}
+
+
+def save_cache(path: Path, cache: dict[str, str]) -> None:
+    """Persist the fingerprint map next to the rendered output."""
+    path.write_text(json.dumps(cache, indent=2, sort_keys=True), encoding="utf-8")

ogcards-0.1.0/src/ogcards/cli.py

@@ -0,0 +1,144 @@
+"""Command-line interface: ``ogcards build | preview | init``."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from dataclasses import asdict
+from pathlib import Path
+
+from ogcards import cache as cache_mod
+from ogcards.config import Theme, load_theme
+from ogcards.errors import OgcardsError
+from ogcards.manifest import Card, load_manifest
+from ogcards.render import render_card
+
+_SAMPLE_TOML = """\
+[canvas]
+width = 1200
+height = 630
+background = "#ffffff"
+
+[templates.post]
+title_size = 64
+title_color = "#1a1a1a"
+meta_size = 28
+meta_color = "#535358"
+accent = "#0645ad"
+padding = 80
+max_title_lines = 3
+"""
+
+_SAMPLE_MANIFEST = {
+    "cards": [
+        {
+            "title": "Your Post Title Goes Here",
+            "subtitle": "June 13, 2026",
+            "template": "post",
+            "out": "assets/og/posts/your-post.png",
+        }
+    ]
+}
+
+
+def _build(args: argparse.Namespace) -> int:
+    theme = load_theme(Path(args.config))
+    manifest = load_manifest(Path(args.manifest))
+    out_dir = Path(args.out_dir)
+    cache_path = out_dir / ".ogcards-cache.json"
+    cache = {} if args.force else cache_mod.load_cache(cache_path)
+    token = _theme_token(theme)
+
+    rendered = skipped = 0
+    for card in manifest.cards:
+        template = theme.template(card.template)
+        fp = cache_mod.fingerprint(card, template, token)
+        dest = out_dir / card.out
+        if not args.force and dest.is_file() and cache.get(card.out) == fp:
+            skipped += 1
+            continue
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        render_card(card, template, theme).save(dest, "PNG", optimize=True)
+        cache[card.out] = fp
+        rendered += 1
+        if args.verbose:
+            print(f"rendered {dest}")
+
+    cache_path.parent.mkdir(parents=True, exist_ok=True)
+    cache_mod.save_cache(cache_path, cache)
+    print(f"ogcards: {rendered} rendered, {skipped} unchanged")
+    return 0
+
+
+def _preview(args: argparse.Namespace) -> int:
+    theme = load_theme(Path(args.config)) if args.config else Theme()
+    card = Card(title=args.title, out=args.out, subtitle=args.subtitle, template=args.template)
+    dest = Path(args.out)
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    render_card(card, theme.template(card.template), theme).save(dest, "PNG", optimize=True)
+    print(f"ogcards: wrote {dest}")
+    return 0
+
+
+def _init(args: argparse.Namespace) -> int:
+    target = Path(args.dir)
+    target.mkdir(parents=True, exist_ok=True)
+    config = target / "ogcards.toml"
+    manifest = target / "og-manifest.json"
+    for path, contents in (
+        (config, _SAMPLE_TOML),
+        (manifest, json.dumps(_SAMPLE_MANIFEST, indent=2) + "\n"),
+    ):
+        if path.exists():
+            print(f"ogcards: {path} exists, leaving it alone")
+        else:
+            path.write_text(contents, encoding="utf-8")
+            print(f"ogcards: wrote {path}")
+    return 0
+
+
+def _theme_token(theme: Theme) -> str:
+    return json.dumps(
+        {"canvas": asdict(theme.canvas), "fonts": asdict(theme.fonts)},
+        sort_keys=True,
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="ogcards",
+        description="Build-time Open Graph card generator for any static site.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    build = sub.add_parser("build", help="render every card in a manifest")
+    build.add_argument("--config", required=True, help="path to ogcards.toml")
+    build.add_argument("--manifest", required=True, help="path to og-manifest.json")
+    build.add_argument("--out-dir", required=True, help="base directory for outputs")
+    build.add_argument("--force", action="store_true", help="ignore the incremental cache")
+    build.add_argument("-v", "--verbose", action="store_true", help="print each rendered path")
+    build.set_defaults(func=_build)
+
+    preview = sub.add_parser("preview", help="render a single card for design iteration")
+    preview.add_argument("--title", required=True)
+    preview.add_argument("--subtitle")
+    preview.add_argument("--template", default="post")
+    preview.add_argument("--config", help="optional ogcards.toml; omit for defaults")
+    preview.add_argument("--out", default="card.png")
+    preview.set_defaults(func=_preview)
+
+    init = sub.add_parser("init", help="write a sample config and manifest")
+    init.add_argument("--dir", default=".")
+    init.set_defaults(func=_init)
+
+    args = parser.parse_args(argv)
+    try:
+        return int(args.func(args))
+    except OgcardsError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())