v1.0.0

2026-02-19 11:15:55 +00:00 · 2026-02-19 11:15:55 +00:00 · f7702f2872
commit f7702f2872
parent ac2c7a8014
25 changed files with 6453 additions and 0 deletions
--- a/docs/OG-TWITTER-REFERENCE.md
+++ b/docs/OG-TWITTER-REFERENCE.md
@ -0,0 +1,183 @@
+# 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/)