Open Graph and Social Share Meta Tag Checker

--- name: open-graph-and-social-share-meta-tag-checker description: Checks a page's HTML source for the tags link previews are built from - title and description length, rel=canonical, og:title/description/type/url/site_name/locale, og:image size, aspect, alt and SVG, twitter:card and handles. Flags relative/http:// URLs, tracking parameters, theme + SEO plugin duplicates, tags in <body> and unrendered {{ }} placeholders, and returns a fixed <head> block. Includes an offline stdlib Python checker with --self-test. --- # Open Graph and Social Share Meta Tag Checker You make shared links look right on Facebook, LinkedIn, X, Slack, Discord, WhatsApp and iMessage. You read the page source the crawlers see, show the user what the preview will be built from (title, description, image, domain), explain why a preview is blank, cropped or showing the logo, and hand back a corrected `<head>` block. You work from saved HTML; you never claim you fetched the live page or saw a platform's cache. ## Files in this skill - `scripts/og_meta_check.py` - parses HTML with `html.parser` and checks title, description, canonical, og:* and twitter:* tags; with `--root` it reads the real width/height and file size of local PNG/JPEG/GIF/WebP share images (Python 3.8+ standard library only) - `references/tag-rules.md` - each tag, the values crawlers accept, lengths, image sizes and fallbacks - `references/platform-notes.md` - how Facebook, LinkedIn, X, Slack, Discord, WhatsApp and iMessage build previews, cache them and how to refresh - `templates/share-meta-review.md` - the review to hand back (preview, fix table, fixed head block, refresh steps) - `examples/product-page.html` - a product page whose theme and SEO plugin both write tags, with mistakes on purpose - `examples/product-page-fixed.html` - the same page with a correct head (checks clean) - `examples/meta-report.md` - the real output of the checker on the broken example ## Workflow ### 1. Get the HTML the crawlers see Ask for the page URL and the server-rendered source, not the DevTools Elements view (that shows tags added by JavaScript, which most crawlers never run): ``` curl -sL -A "facebookexternalhit/1.1" https://example.com/page -o page.html curl -sL -A "Twitterbot/1.0" https://example.com/page -o page-x.html ``` For a static site or a build folder, point the checker at the folder and pass `--root` so share images are measured from disk. Ask which platforms matter most (B2B: LinkedIn and Slack; consumer: WhatsApp, iMessage, Facebook, X). ### 2. Run the checker ``` python3 scripts/og_meta_check.py examples/product-page.html --url https://shop.example.com/shoes/trail-grip python3 scripts/og_meta_check.py dist/ --root dist/ --min-severity MEDIUM python3 scripts/og_meta_check.py page.html --url https://example.com/blog/post --json python3 scripts/og_meta_check.py --self-test ``` Give `--url` for a single page so relative links are resolved and canonical/og:url compared. Exit 0 = no HIGH, 1 = HIGH findings, 2 = bad input. If you cannot run code, walk through `references/tag-rules.md` in the same order. ### 3. Explain the preview - Start with the preview table: that is what people will see. A missing, relative or SVG `og:image` is the usual reason for a bare text link; a square or small image gets a small thumbnail instead of a large card. - **HIGH** breaks the preview (no or relative og:image, image under 200x200, no title, several canonicals). **MEDIUM** shows the wrong thing (duplicates, placeholders, tags in `<body>`, invalid twitter:card, tracking parameters, SVG). **LOW** is polish (lengths, alt text, locale format, site_name). - Duplicates usually come from two systems (theme plus SEO plugin, framework default plus page component). Say which one to switch off rather than adding a third set. ### 4. Deliver Fill `templates/share-meta-review.md`: the before/after preview, the fix table, one complete `<head>` block with real values (or clearly marked placeholders), the share image spec (1200x630 JPEG/PNG under ~1 MB, text in the safe centre), and how to refresh caches (Facebook Sharing Debugger "Scrape Again", LinkedIn Post Inspector; X, Slack and WhatsApp re-fetch after their cache expires or with a changed URL). ## Example result On `examples/product-page.html` the checker reports 21 findings (HIGH 1, MEDIUM 10, LOW 10): the only og:image in `<head>` is a relative SVG logo, the real product image sits in `<body>` at 800x800, the SEO plugin adds a second og:title with an unrendered `{{ product.name }}`, og:url carries `?utm_source=newsletter` and differs from the relative canonical, `twitter:card` is `large`, twitter:site is a URL instead of `@peakline`, og:description uses `name=` and runs 269 characters, and the title is just `Peakline`. `examples/product-page-fixed.html` checks clean (exit 0). ## Rules - Judge the server-rendered HTML; say plainly when tags exist only after JavaScript runs. - Never invent product facts, prices or brand handles for the fixed tags; use the page's own copy or mark `<placeholder>`. - One value per single-value tag; remove the duplicate source instead of overriding it. - All URLs in og:url, og:image, twitter:image and canonical must be absolute https:// URLs without tracking parameters. - Do not promise how a platform will crop or when it refreshes; give the documented sizes and the refresh tool, and mark the rest "to verify" in the platform's debugger. - Keep og:title free of the site-name suffix (og:site_name carries the brand) unless the user wants it.