Images

OmarCMS includes a convention-based image system for blog posts. No configuration needed - just drop images in the right folder.

Hero Images

Hero images appear at the top of blog posts, after the title and before the content.

Adding a Hero Image

Place your image at public/images/blog/[post-slug]/hero.jpg:

public/
  images/
    blog/
      my-post/
        hero.jpg

The image will automatically appear on /blog/my-post. No frontmatter configuration needed.

Image Specifications

  • Dimensions: 1200×630 pixels (16:9 aspect ratio)
  • Format: JPEG (best for photos)
  • Max size: 500KB (for fast page loads)

Alt Text & Attribution

Add descriptive alt text and image credits in your post frontmatter:

---
title: "My Post"
date: "2026-02-14"
heroAlt: "A detailed description of the image for screen readers"
imageCredit: "Photo by Photographer Name (Source)"
---

Finding Images

OmarCMS includes a helper script to find and download Creative Commons images from Wikimedia Commons:

Using the Image Finder

./scripts/find-hero.sh "search query" post-slug

Example:

./scripts/find-hero.sh "mountain landscape" my-hiking-post

This will:

  1. Search Wikimedia Commons for relevant images
  2. Download the best match
  3. Resize it to exactly 1200×630
  4. Save to public/images/blog/my-hiking-post/hero.jpg
  5. Output suggested frontmatter for alt text and credit

Image Sources

  • Wikimedia Commons - Free, Creative Commons images (built-in script)
  • Unsplash - High-quality photos (requires API key)
  • Your own photos - Just resize to 1200×630 and place in the right folder

Inline Images

For images within your post content, place them in the same folder:

public/
  images/
    blog/
      my-post/
        hero.jpg
        diagram.png
        screenshot.jpg

Reference them in your markdown:

![Diagram showing the architecture](/images/blog/my-post/diagram.png)

Inline Image Guidelines

  • Max width: 800px (readable on all devices)
  • Format: PNG for diagrams/screenshots, JPEG for photos
  • Always include alt text in the markdown image syntax

Posts Without Images

Images are completely optional. Posts without hero images work perfectly fine - they just won't show a hero section.

Resizing Images

If you have an image that's not the right size, use the built-in sips command (macOS) or ImageMagick:

macOS (sips)

sips -z 630 1200 input.jpg --out hero.jpg

ImageMagick (all platforms)

convert input.jpg -resize 1200x630^ \
  -gravity center -extent 1200x630 hero.jpg

Example Workflow

Here's a complete example of adding an image to a post:

# 1. Write your post
cat > src/content/blog/my-post.md << 'EOF'
---
title: "My New Post"
date: "2026-02-14"
description: "A post about something interesting"
heroAlt: "A beautiful mountain landscape at sunset"
imageCredit: "Mountain photo (Wikimedia Commons)"
---

Content here...
EOF

# 2. Find and download an image
./scripts/find-hero.sh "mountain sunset" my-post

# 3. Commit and push
git add -A
git commit -m "New post: My New Post"
git push

# Done! Your post is live with a hero image

Tips

  • Choose relevant images - The image should relate to your content
  • Write good alt text - Describe what's in the image, not just the topic
  • Credit your sources - Always attribute Creative Commons images
  • Optimize file size - Use JPEG quality 85-90 for good balance
  • Test on mobile - Make sure images look good on small screens

Next Steps