Writing guide: OG images, titles, descriptions, and dates

This site auto-generates all Open Graph and Twitter metadata from your post’s front matter and/or first content image. Follow these simple rules to guarantee great share cards and accurate dates in Google.

Minimum front matter for a post

---
title: "Your post title"
layout: post
# Primary share image (preferred)
image: /assets/images/your-image-1200x630.jpg
# Fallback if you keep using the older field name
# image_url: https://.../your-image-1200x630.jpg
# Optional: custom description (otherwise the excerpt is used)
description: A crisp 1–2 sentence summary (max ~150–160 chars).
# Publish date (required); format: YYYY-MM-DD HH:MM
date: 2025-06-22 00:00
# Update this when you substantially revise a post (optional but recommended)
last_modified_at: 2025-06-25 13:30
---

Notes:

• Use image when possible (path under this repo). Absolute URLs also work.
• If image is missing, the site tries image_url. If both are missing, it automatically chooses the first <img> in your content; if none, it falls back to the site avatar.
• The layout converts the image to an absolute URL and sets both og:image and twitter:image with twitter:card=summary_large_image.

Image recommendations

• Size: 1200×630 px (minimum 600×315 px).
• Format: JPEG or PNG; keep size under ~300 KB if possible.
• Avoid transparent PNGs for OG images.
• Include width/height in Markdown when convenient to reduce CLS: ![Alt text](/assets/images/your-image.jpg){: width="1200" height="630" } (optional)

Titles and descriptions

• The page <title> is Writing guide: OG images, titles, descriptions, and dates | Sameer Bajaj.
• Description uses, in order: page.excerpt → page.description → site.description.
• Keep descriptions concise and human-readable; avoid quotes in YAML that would need escaping.

Dates and Google freshness

• date is the publish date; it appears in the UI and feeds.
• last_modified_at is used to signal updates to crawlers:
  • Added to article:modified_time and og:updated_time.
  • Used as dateModified in JSON‑LD (BlogPosting).
• To refresh the “updated” signal, bump last_modified_at when you materially update content (don’t change date unless you’re republishing).

Example update:

last_modified_at: 2025-07-01 09:10

Validation checklist (2 minutes)

1. Open the built page, View Source.
2. Confirm these meta tags exist and are correct:
   • og:image (absolute URL) and twitter:image.
   • twitter:card = summary_large_image.
   • article:published_time and article:modified_time (for posts).
3. Test the URL in:
   • Twitter Card Validator (large image)
   • Facebook Sharing Debugger / Meta Open Graph debugger

Troubleshooting

• Image not showing? Ensure the image URL is reachable and uses https. For relative paths, the site makes them absolute automatically at build time.
• Wrong image? Set image: explicitly in front matter.
• Description looks odd? Provide a description: or refine the first paragraph used in the excerpt.

That’s it. New posts inherit all logic; set image, description (optional), and last_modified_at when you update content. No other steps required.