Automate social image generation

.github/workflows/social-images.yml

@@ -0,0 +1,94 @@
+name: Social Images
+
+on:
+  pull_request:
+    paths:
+      - 'content/**/*.md'
+
+jobs:
+  generate:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+        with:
+          ref: ${{ github.head_ref }}
+          repository: ${{ github.event.pull_request.head.repo.full_name }}
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5
+        with:
+          python-version: '3.x'
+
+      - name: Install ImageMagick
+        run: |
+          sudo apt-get update -qq
+          sudo apt-get install -y imagemagick
+          # Ubuntu ships ImageMagick 6 (binary: convert). generate.py expects `magick`
+          # (IM7 name). Create an alias so the script works without modification.
+          sudo ln -sf /usr/bin/convert /usr/local/bin/magick
+          magick -version
+
+      - name: Install Python dependencies
+        run: pip install -r scripts/social-images/requirements.txt
+
+      - name: Find changed Markdown files
+        id: diff
+        run: |
+          git fetch --depth=1 origin ${{ github.event.pull_request.base.sha }}
+
+          git diff --name-only --diff-filter=AM FETCH_HEAD HEAD \
+            | grep '^content/.*\.md$' > /tmp/added_modified.txt || true
+
+          git diff --name-only --diff-filter=DR FETCH_HEAD HEAD \
+            | grep '^content/.*\.md$' > /tmp/deleted.txt || true
+
+          echo "has_added=$([ -s /tmp/added_modified.txt ] && echo 'true' || echo 'false')" >> "$GITHUB_OUTPUT"
+          echo "has_deleted=$([ -s /tmp/deleted.txt ] && echo 'true' || echo 'false')" >> "$GITHUB_OUTPUT"
+
+      - name: Generate social images for added/modified files
+        if: steps.diff.outputs.has_added == 'true'
+        run: |
+          while IFS= read -r f; do
+            echo "Generating: $f"
+            python3 scripts/social-images/generate.py --file "$f" --force
+          done < /tmp/added_modified.txt
+
+      - name: Remove orphaned images for deleted files
+        if: steps.diff.outputs.has_deleted == 'true'
+        run: |
+          while IFS= read -r f; do
+            # Mirror ContentFile._detect_type (generate.py:170): first segment after content/
+            type="${f#content/}"
+            type="${type%%/*}"
+            # Mirror ContentFile._derive_slug (generate.py:178): parent dir for index files, else stem
+            filename="$(basename "$f")"
+            if [[ "$filename" == "index.md" || "$filename" == "_index.md" ]]; then
+              slug="$(basename "$(dirname "$f")")"
+            else
+              slug="${filename%.md}"
+            fi
+            img="static/images/social/${type}/${slug}.png"
+            echo "Removing orphan: $img"
+            git rm -f --ignore-unmatch "$img"
+          done < /tmp/deleted.txt
+
+      - name: Commit and push images
+        if: github.event.pull_request.head.repo.full_name == github.repository
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add static/images/social/
+          if git diff --cached --quiet; then
+            echo "No image changes to commit."
+          else
+            git commit -m "chore(social-images): sync images for changed content"
+            git push
+          fi
+
+      - name: Notice for fork PRs
+        if: github.event.pull_request.head.repo.full_name != github.repository
+        run: |
+          echo "::notice::Fork PR — social images not committed automatically. Run 'python3 scripts/social-images/generate.py' locally (needs ImageMagick + Python deps) or ask a maintainer to regenerate."

.gitignore

@@ -59,4 +59,4 @@ haystack-advent
 content/advent-of-haystack/*
 !content/advent-of-haystack/_index.md
 
-static/downloads
+static/downloads

assets/jsconfig.json

@@ -3,7 +3,7 @@
   "baseUrl": ".",
   "paths": {
    "*": [
-    "..\\themes\\haystack\\assets\\*"
+    "../themes/haystack/assets/*"
    ]
   }
  }

scripts/social-images/README.md

@@ -0,0 +1,121 @@
+# Social image generation
+
+Generates Open Graph / Twitter Card preview images for Hugo content by compositing text onto PNG templates using ImageMagick.
+
+Images are placed at `static/images/social/{type}/{slug}.png`. Hugo's `opengraph.html` partial automatically detects a generated image at that path and uses it — no front-matter changes needed in any content file.
+
+## Prerequisites
+
+```bash
+brew install imagemagick
+pip3 install -r scripts/social-images/requirements.txt
+```
+
+## CI integration
+
+`.github/workflows/social-images.yml` runs on every PR that changes a `content/**/*.md` file. It generates or removes images for the changed files and commits them back to the PR branch via `github-actions[bot]`. No local tooling required.
+
+Fork PRs emit a workflow notice instead — run `generate.py` locally or ask a maintainer.
+
+## Local usage
+
+```bash
+# Preview everything without writing files
+python3 scripts/social-images/generate.py --dry-run
+
+# Generate for all content types
+python3 scripts/social-images/generate.py
+
+# One content type only
+python3 scripts/social-images/generate.py --type release-notes
+
+# Single file
+python3 scripts/social-images/generate.py --file content/release-notes/2.25.0.md
+```
+
+## Adding templates
+
+Place one PNG per content type in `scripts/social-images/templates/`:
+
+| File | Used for |
+|---|---|
+| `blog.png` | `content/blog/` posts |
+| `release-notes.png` | `content/release-notes/` pages |
+| `tutorials.png` | `content/tutorials/` pages |
+| `cookbook.png` | `content/cookbook/` pages |
+| `Integration.png` | `content/integrations/` pages |
+| `fallback.png` | Everything else |
+
+Recommended size: **1200 × 630 px** (standard OG image ratio).
+
+## Configuration
+
+`config.yaml` controls text placement for each template. Each content type can define multiple named fields (`title`, `description`, etc.) that map to front-matter values.
+
+Use `exclude:` to skip content types entirely (e.g. blog posts that already have their own thumbnail):
+
+```yaml
+exclude:
+  - blog
+  - authors
+
+templates:
+  release-notes:
+    template: scripts/social-images/templates/release-notes.png
+    fields:
+      title:
+        font: scripts/social-images/fonts/HafferBold.ttf
+        size: 48           # font size in points
+        color: "#2558ff"
+        gravity: NorthWest # ImageMagick anchor: NorthWest, Center, South, etc.
+        left: 66           # pixel offset from the gravity anchor (horizontal)
+        top: 232           # pixel offset from the gravity anchor (vertical)
+        max_width: 830     # text wraps within this box width
+        max_height: 165    # text is clipped beyond this height
+      description:
+        font: scripts/social-images/fonts/Inter-Regular.ttf
+        size: 20
+        color: "#2558ff"
+        gravity: NorthWest
+        left: 66
+        anchor: title      # position below the rendered bottom of the title field
+        gap: 15            # extra pixels of padding after the title
+        max_width: 830     # text wraps within this box width
+        max_height: 165    # text is clipped beyond this height
+```
+
+**Field reference:**
+
+| Key | Required | Description |
+|---|---|---|
+| `font` | yes | Path to a TTF file (relative to repo root) |
+| `size` | yes | Font size in points (matches Canva pt values at 96 DPI) |
+| `color` | yes | Hex color string |
+| `gravity` | yes | ImageMagick reference corner: `NorthWest`, `Center`, `South`, etc. |
+| `left` | yes* | Horizontal pixel offset from the gravity anchor (*defaults to anchor's `left` when `anchor` is set) |
+| `top` | yes* | Vertical pixel offset from the gravity anchor (*not needed when `anchor` is set) |
+| `max_width` | yes | Caption box width in pixels (controls line wrapping) |
+| `max_height` | yes | Caption box height in pixels (text is clipped if it overflows) |
+| `anchor` | no | Name of another field; positions this field's top below that field's rendered bottom edge |
+| `gap` | no | Extra pixels of padding below the anchor field (default: 0) |
+
+**Dynamic positioning with `anchor`:** when set, the canvas position is computed so that exactly `gap` pixels of visual space appear between the anchor's last text pixel and this field's first text pixel:
+
+```
+canvas_top = anchor_field.top + anchor_bottom_offset + gap - this_field_top_offset
+```
+
+`gap: 0` means the two text blocks touch with no overlap and no extra space. Both offsets are measured from each field's own caption canvas using ImageMagick's trim geometry.
+
+Available fonts (in `scripts/social-images/fonts/`):
+
+- `HafferBold.ttf`, `HafferMedium.ttf`, `HafferRegular.ttf` — Haffer (headings + body)
+- `Inter-Regular.ttf` — Inter (body text)
+
+## How Hugo picks up the images
+
+`themes/haystack/layouts/partials/opengraph.html` derives the expected image path from the page's content type and slug, then checks for the file with `os.FileExists`. Priority order:
+
+1. Explicit `images` array in front matter (manual override)
+2. Generated social image at `static/images/social/{type}/{slug}.png`
+3. Site-wide default from `config.toml`

scripts/social-images/config.yaml

@@ -0,0 +1,146 @@
+# Social image generation configuration.
+#
+# Each key under `templates` maps to a content type inferred from the file path
+# (e.g. content/blog/ → "blog").  If a content type has no entry here, the
+# "fallback" template is used.
+#
+# Field keys are arbitrary — they must match a front-matter key that the script
+# knows how to read (title, description).  The script skips a field silently if
+# the front-matter value is empty.
+#
+# Field options:
+#   font       - path to a TTF file (relative to the repo root)
+#   size       - font size in points (matches Canva pt values; rendered at 96 DPI)
+#   color      - hex color string
+#   gravity    - ImageMagick gravity: NorthWest, North, NorthEast, West, Center,
+#                East, SouthWest, South, SouthEast
+#   left       - pixel offset from the gravity anchor (horizontal; required unless anchor is
+#                set, in which case it defaults to the anchor field's left value)
+#   top        - pixel offset from the gravity anchor (vertical; required unless anchor is set)
+#   max_width  - caption box width in pixels (controls line wrapping)
+#   max_height - caption box height in pixels (text is clipped if it overflows)
+#   anchor     - (optional) name of another field whose rendered bottom edge
+#                determines this field's top; replaces top
+#   gap        - (optional) extra pixels of padding below the anchor (default 0)
+
+# Content types listed here are skipped entirely (no image generated).
+exclude:
+  - blog
+  - authors
+  - ambassador-perks
+
+templates:
+  cookbook:
+    template: scripts/social-images/templates/cookbook.png
+    fields:
+      title:
+        font: scripts/social-images/fonts/HafferBold.ttf
+        size: 48
+        color: "#2558ff"
+        gravity: NorthWest
+        left: 66
+        top: 232
+        max_width: 830
+        max_height: 165
+      description:
+        font: scripts/social-images/fonts/Inter-Regular.ttf
+        size: 20
+        color: "#2558ff"
+        gravity: NorthWest
+        left: 66
+        anchor: title
+        gap: 15
+        max_width: 830
+        max_height: 165
+
+  integrations:
+    template: scripts/social-images/templates/Integration.png
+    fields:
+      title:
+        font: scripts/social-images/fonts/HafferBold.ttf
+        size: 48
+        color: "#2558ff"
+        gravity: NorthWest
+        left: 66
+        top: 232
+        max_width: 830
+        max_height: 165
+      description:
+        font: scripts/social-images/fonts/Inter-Regular.ttf
+        size: 20
+        color: "#2558ff"
+        gravity: NorthWest
+        left: 66
+        anchor: title
+        gap: 15
+        max_width: 830
+        max_height: 165
+
+  release-notes:
+    template: scripts/social-images/templates/release-notes.png
+    fields:
+      title:
+        font: scripts/social-images/fonts/HafferBold.ttf
+        size: 48
+        color: "#2558ff"
+        gravity: NorthWest
+        left: 66
+        top: 232
+        max_width: 830
+        max_height: 165
+      description:
+        font: scripts/social-images/fonts/Inter-Regular.ttf
+        size: 20
+        color: "#2558ff"
+        gravity: NorthWest
+        left: 66
+        anchor: title
+        gap: 15
+        max_width: 830
+        max_height: 165
+
+  tutorials:
+    template: scripts/social-images/templates/tutorials.png
+    fields:
+      title:
+        font: scripts/social-images/fonts/HafferBold.ttf
+        size: 48
+        color: "#2558ff"
+        gravity: NorthWest
+        left: 66
+        top: 232
+        max_width: 830
+        max_height: 165
+      description:
+        font: scripts/social-images/fonts/Inter-Regular.ttf
+        size: 20
+        color: "#2558ff"
+        gravity: NorthWest
+        left: 66
+        anchor: title
+        gap: 15
+        max_width: 830
+        max_height: 165
+
+  fallback:
+    template: scripts/social-images/templates/fallback.png
+    fields:
+      title:
+        font: scripts/social-images/fonts/HafferBold.ttf
+        size: 48
+        color: "#2558ff"
+        gravity: NorthWest
+        left: 66
+        top: 232
+        max_width: 830
+        max_height: 165
+      description:
+        font: scripts/social-images/fonts/Inter-Regular.ttf
+        size: 20
+        color: "#2558ff"
+        gravity: NorthWest
+        left: 66
+        anchor: title
+        gap: 15
+        max_width: 830
+        max_height: 165