4.9 KiB
Using Images in Blog Posts
Learn how to add header images, inline images, and Open Graph images to your markdown posts.
Type: post Date: 2025-12-14 Reading time: 4 min read Tags: images, tutorial, markdown, open-graph
Using Images in Blog Posts
This post demonstrates how to add images to your blog posts. You can use header images for social sharing, inline images for content, and set Open Graph images for better link previews.
Header/Open Graph Images
The image field in your frontmatter serves multiple purposes:
- Open Graph image for social media previews (Twitter, LinkedIn, Slack)
- Thumbnail image for featured section card view on the homepage
- Header image displayed at the top of the post/page (when
showImageAtTop: true)
---
title: "Your Post Title"
image: "https://images.unsplash.com/photo-1499750310107-5fef28a66643?w=1200&h=630&fit=crop"
showImageAtTop: true
---
Recommended dimensions: 1200x630 pixels (1.91:1 ratio) for social sharing
Displaying Image at Top of Post/Page
To display the image field at the top of your post or page (above the header), add showImageAtTop: true to your frontmatter:
---
title: "My Post"
image: "https://images.unsplash.com/photo-1499750310107-5fef28a66643?w=1200&h=630&fit=crop"
showImageAtTop: true
---
Default behavior: If showImageAtTop is not set or set to false, the image will only be used for Open Graph previews and featured card thumbnails, not displayed in the post content.
Use cases:
- Hero images for blog posts
- Featured images that introduce the content
- Visual headers for documentation pages
Featured Section Thumbnails
When a post or page is marked as featured: true, the image field displays as a square thumbnail in the card view.
---
title: "Featured Post"
image: "/images/thumbnail.png"
featured: true
featuredOrder: 1
---
Square display: Non-square images are automatically cropped to fit the square thumbnail area. The crop centers on the middle of the image. For best results, use images where the main subject is centered.
Square thumbnails: 400x400px minimum (800x800px for retina)
Inline Images
You can add images using markdown syntax or HTML. The site uses rehypeRaw and rehypeSanitize to safely render HTML in markdown content.
Markdown Syntax
Add images anywhere in your markdown content using standard syntax:
Here's an example image from Unsplash:
The alt text appears as a caption below the image.
HTML Syntax
You can also use HTML <img> tags directly in your markdown:
<img src="/images/screenshot.png" alt="Alt text description" />
Or with additional attributes:
<img
src="https://images.unsplash.com/photo-1499750310107-5fef28a66643?w=800&h=450&fit=crop"
alt="Laptop on a wooden desk with coffee and notebook"
width="800"
height="450"
/>
HTML images: HTML <img> tags are sanitized for security using rehypeSanitize. Allowed attributes include src, alt, width, height, loading, and class. The alt text still appears as a caption below HTML images, matching the markdown behavior.
Combining markdown and HTML: You can mix markdown and HTML in the same post. Both syntaxes render images with the same styling and caption behavior.
Image Sources
You can use images from:
| Source | Example |
|---|---|
| Local files | /images/my-image.png |
| Unsplash | https://images.unsplash.com/... |
| Cloudinary | https://res.cloudinary.com/... |
| Any CDN | Full URL to image |
Local Images
Place image files in the public/images/ directory:
public/
images/
screenshot.png
diagram.svg
photo.jpg
Reference them with a leading slash:
External Images
Use the full URL for images hosted elsewhere:
Here's a coding-themed image:
Best Practices
- Use descriptive alt text for accessibility
- Optimize image size before uploading (compress PNG/JPG)
- Use CDN URLs for external images when possible
- Match OG image dimensions to 1200x630 for social previews
- Use SVG for logos and icons
Free Image Resources
These sites offer free, high-quality images:
- Unsplash - Photos
- Pexels - Photos and videos
- unDraw - Illustrations
- Heroicons - Icons
- Phosphor Icons - Icons