# New Page: OG Image and Social Preview Checklist

**Last Updated:** 2026-03-25

Use this checklist whenever you publish a **new** public URL (tools, templates, downloads, webinars, comparison pages, product/industry slugs, or other marketing pages). Goal: a **tailored** 1200×630 WebP, correct registry wiring, complete meta tags, and post-deploy cache refresh.

**See also:** [OG_IMAGE_GUIDE.md](OG_IMAGE_GUIDE.md) (architecture, validators), [WEBSITE_PAGE_PUBLICATION_INDEX.md](../../content/WEBSITE_PAGE_PUBLICATION_INDEX.md) (full page-family map), `.cursor/rules/og-image-generation.mdc`.

## Preconditions

- [ ] Page slug is final (matches URL and registry keys).
- [ ] Page title / H1 is stable enough to derive the OG **headline** (often shortened; use `<br>` in JSON only if the HTML template supports it—see existing specs).

## Step 1 – Specs

- [ ] Add an entry to [`v2/scripts/og-images/og-image-specs.json`](../../../v2/scripts/og-images/og-image-specs.json):

  - `headline`: German, matches share card intent (e.g. `Pendlerpauschale-Rechner`).
  - `visual`: base illustration key (`tools`, `template`, `download`, `comparison`, etc.) for SVG mode and for Gemini fallback keys.

## Step 2 – Gemini hybrid (recommended for tools/templates/marketing pages)

If you run `generate-og-images.py --type={slug} --gemini-visuals`:

- [ ] Add **`VISUAL_DESCRIPTIONS[{slug}]`** in [`v2/scripts/og-images/generate-og-image-gemini.py`](../../../v2/scripts/og-images/generate-og-image-gemini.py) (full-image fallback text).
- [ ] Add **`VISUAL_ONLY_PROMPTS[{slug}]`** in the same file (right-panel-only prompt). **Required** for hybrid generation: missing keys cause `Unknown page type for visual` and block Gemini for that slug.
- [ ] Follow visual rules: **no text, numbers, or labels** in the illustration; isometric 3D; white background; #4D8EF3 accents—see [OG_IMAGE_GUIDE.md](OG_IMAGE_GUIDE.md) → Reference Style.

If you only use Playwright + SVG (no Gemini):

- [ ] Skip the two Python dict entries; ensure `visual` in specs maps to an existing illustration key.

## Step 3 – Generate asset

- [ ] **API key** available (`GEMINI_API_KEY` in `.env` or `v2/config/gemini-api-key.php`; see [GEMINI_API_KEY_LOCAL.md](../../development/GEMINI_API_KEY_LOCAL.md)) if using `--gemini-visuals`.
- [ ] Run:

  ```bash
  python3 v2/scripts/og-images/generate-og-images.py --type={slug} --gemini-visuals --workers 1
  ```

  Or without Gemini:

  ```bash
  python3 v2/scripts/og-images/generate-og-images.py --type={slug}
  ```

- [ ] Output: `v2/img/og/{slug}.webp` (comparison pages: `comparison-{slug}.webp` per comparison pipeline).

## Step 4 – Validate

- [ ] `python3 v2/scripts/og-images/validate-og-images.py`
- [ ] `python3 v2/scripts/og-images/validate-og-logo.py`
- [ ] Drift audit (tools hub): `python3 v2/scripts/og-images/audit-og-publish-readiness.py` (add `--require-gemini-prompts` if enforcing Gemini dicts).

## Step 5 – Registry and PHP

- [ ] Add or confirm slug in [`v2/config/og-image-registry.php`](../../../v2/config/og-image-registry.php) `$page_specific` (or correct comparison pattern) so `get_og_image_for_page()` resolves the custom file—not the generic type default.
- [ ] Page PHP uses `render_og_meta_tags()` with **`og_image_alt`** describing the page (accessibility + Twitter alt).

## Step 6 – Inventory doc (optional but recommended)

- [ ] Add a row to [OG_IMAGE_ASSET_CHECKLIST.md](OG_IMAGE_ASSET_CHECKLIST.md) for new standalone assets.

## Step 7 – After deploy

- [ ] Facebook Sharing Debugger: scrape again.
- [ ] LinkedIn Post Inspector / X Card Validator as needed.
- [ ] Expect Slack cache delay (24–48h possible).

## Quick reference commands

| Action | Command |
|--------|---------|
| Generate (Gemini right panel) | `python3 v2/scripts/og-images/generate-og-images.py --type=SLUG --gemini-visuals --workers 1` |
| Validate dimensions / color | `python3 v2/scripts/og-images/validate-og-images.py` |
| Validate logo region | `python3 v2/scripts/og-images/validate-og-logo.py` |
| Publish readiness (tools) | `python3 v2/scripts/og-images/audit-og-publish-readiness.py` |
| Local HTML OG scan | `php v2/scripts/dev-helpers/validate-og-images.php --local` |