# Open Graph & Twitter Cards — Reference

This document covers the Open Graph (OG) and Twitter Cards meta tag specifications relevant to this plugin, including which tags are mandatory, recommended, optional, and which this plugin outputs automatically.

---

## Open Graph Protocol

Defined by Facebook/Meta. All OG tags use the `property` attribute.

### Core Tags (og: namespace)

| Property | Type | Required | Notes |
|---|---|---|---|
| `og:title` | string | **Required** | Title of the content. Used by all social crawlers. |
| `og:type` | string | **Required** | Content type: `website`, `article`, `video.movie`, etc. |
| `og:url` | URL | **Required** | Canonical URL of the page. |
| `og:description` | string | Recommended | Short description (2–4 sentences). Max ~300 chars. |
| `og:site_name` | string | Recommended | Name of the overall site (e.g. "My Blog"). |
| `og:locale` | string | Recommended | Locale in `language_TERRITORY` format (e.g. `es_ES`). |
| `og:image` | URL | **Required** (for cards) | Must be JPEG or PNG for social crawler compatibility. Min 200×200 px. Recommended 1200×630 px. |
| `og:image:secure_url` | URL | Optional | HTTPS version of `og:image`. Same value when the site is HTTPS-only. |
| `og:image:type` | MIME type | Recommended | MIME type of the image (`image/jpeg`, `image/png`). |
| `og:image:width` | integer | Recommended | Width in pixels. Avoids reflow in crawler previews. |
| `og:image:height` | integer | Recommended | Height in pixels. |
| `og:image:alt` | string | Recommended | Alt text for the image. Required for accessibility audits. |

### Article Tags (article: namespace)

Used when `og:type = article`. All are optional but recommended for news/blog content.

| Property | Type | Notes |
|---|---|---|
| `article:published_time` | ISO 8601 datetime | Publication date (`c` format in PHP: `get_the_date('c')`). |
| `article:modified_time` | ISO 8601 datetime | Last modification date. |
| `article:author` | URL | Profile page of the author (Facebook profile URL). Often omitted. |
| `article:section` | string | Primary category or section (e.g. "Technology"). |
| `article:tag` | string | Topic tags. Can be repeated once per tag. |
| `article:expiration_time` | ISO 8601 datetime | When the article expires (rarely used). |

### Video Tags (video: namespace)

For `og:type = video.movie`, `video.episode`, etc. Out of scope for this plugin.

---

## Twitter Cards

Defined by X (formerly Twitter). Tags use the `name` attribute (not `property`).

Twitter falls back to `og:*` tags if the corresponding `twitter:*` tag is absent — **except** `twitter:card`, which is always required.

### Card Types

| Value | Description |
|---|---|
| `summary` | Small square image (minimum 144×144 px). |
| `summary_large_image` | Large rectangular image (minimum 300×157 px, recommended 1200×628 px). Most common for blog/news content. |
| `app` | Promotes a mobile app. |
| `player` | Embeds a video/audio player. |

### Twitter Tags

| Name | Required | Falls back to | Notes |
|---|---|---|---|
| `twitter:card` | **Required** | — | Must always be present. Without it, no Twitter Card is shown. |
| `twitter:site` | Recommended | — | `@username` of the site's Twitter/X account. |
| `twitter:creator` | Optional | — | `@username` of the content author. |
| `twitter:title` | Recommended | `og:title` | Title of the content. |
| `twitter:description` | Recommended | `og:description` | Description. Max 200 chars. |
| `twitter:image` | Recommended | `og:image` | Must be JPEG, PNG, WebP, or GIF. Max 5 MB. |
| `twitter:image:alt` | Recommended | `og:image:alt` | Alt text for the image. Max 420 chars. |

---

## What This Plugin Outputs

### When no SEO plugin is active (direct injection)

The plugin outputs a **complete** set of OG and Twitter Card tags via `wp_head` (priority 5).

#### Open Graph tags

```html
<!-- Core -->
<meta property="og:title" content="..." />
<meta property="og:type" content="article" />     <!-- or "website" -->
<meta property="og:url" content="..." />
<meta property="og:description" content="..." />  <!-- when available -->
<meta property="og:site_name" content="..." />
<meta property="og:locale" content="es_ES" />

<!-- Image (when a compatible image is resolved) -->
<meta property="og:image" content="https://...jpg" />
<meta property="og:image:secure_url" content="https://...jpg" />  <!-- HTTPS only -->
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />
<meta property="og:image:type" content="image/jpeg" />
<meta property="og:image:alt" content="..." />  <!-- when set in media library -->

<!-- Article-specific (og:type = article only) -->
<meta property="article:published_time" content="2026-02-18T00:00:00+00:00" />
<meta property="article:modified_time" content="2026-02-18T00:00:00+00:00" />
<meta property="article:section" content="Technology" />  <!-- primary category -->
<meta property="article:tag" content="WordPress" />       <!-- repeated per tag -->
```

#### Twitter Card tags

```html
<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:site" content="@example" />  <!-- when configured in Settings -->
<meta name="twitter:image" content="https://...jpg" />  <!-- when image available -->
```

> Twitter falls back to `og:title`, `og:description`, and `og:image` automatically, so those tags are not duplicated.

### When Yoast SEO or RankMath is active

The plugin acts as a **corrector only**: it filters the image URL via the SEO plugin's filter hook, converting incompatible formats (AVIF/WebP) to JPEG/PNG. All other OG/Twitter tags are managed by the SEO plugin.

---

## og:type Values Reference

| Value | When to use |
|---|---|
| `website` | Default for homepages and most pages. |
| `article` | Blog posts, news articles. This plugin uses this for `is_singular('post')`. |
| `profile` | User profile pages. |
| `video.movie` | Movie pages. |
| `video.episode` | TV episode pages. |
| `music.song` | Song pages. |
| `music.album` | Album pages. |

---

## Per-Post Overrides (Editor Meta Box)

The plugin adds an **"Open Graph / Social Media"** meta box to all post editors, allowing per-post overrides of:

| Field | OG Tag | Fallback |
|---|---|---|
| Custom Title | `og:title` | Post title (`get_the_title()`) |
| Custom Description | `og:description` | Post excerpt, or empty |

These overrides are stored as post meta:
- `_og_title` — custom OG title
- `_og_description` — custom OG description

---

## Context → og:type Mapping (this plugin)

| WordPress context | `og:type` |
|---|---|
| `is_singular('post')` | `article` |
| `is_singular('page')` | `website` |
| `is_singular(other)` | `website` |
| `is_front_page()` / `is_home()` | `website` |
| `is_tax()` / `is_category()` / `is_tag()` | `website` |

---

## Image Compatibility

Social crawlers (Facebook, X, LinkedIn, WhatsApp, Telegram) generally require:
- Format: **JPEG or PNG** (WebP partial support; AVIF not supported)
- Minimum size: 200×200 px (Facebook requires 200×200 for `summary`)
- Recommended: 1200×630 px for `summary_large_image`
- Max file size: 8 MB (Facebook), 5 MB (Twitter)

This plugin's core function is to detect when a featured image is in an incompatible format (AVIF, WebP) and automatically serve a JPEG/PNG alternative via fallback resolution.

---

## Validation Tools

- **Facebook**: [Sharing Debugger](https://developers.facebook.com/tools/debug/)
- **Twitter/X**: [Card Validator](https://cards-dev.twitter.com/validator)
- **LinkedIn**: [Post Inspector](https://www.linkedin.com/post-inspector/)
- **OpenGraph.xyz**: [OpenGraph preview](https://www.opengraph.xyz/)
- **Metatags.io**: [Meta tag preview](https://metatags.io/)