Skip to main content

Blog Featured Images Documentation

This document outlines how to use featured images in Trading Card API documentation blog posts.

Overview​

Featured images enhance blog posts by providing visual appeal and improving social media sharing. Images are displayed in two locations:

  1. Blog list page - Thumbnail view with the post preview
  2. Individual blog post - Hero image at the top of the post
  3. Social media sharing - Enhanced Open Graph and Twitter Card previews

1. Image Preparation​

Requirements:

  • Formats: JPG, PNG, or WebP
  • Dimensions: Minimum 1200x630px (optimal for social sharing)
  • File Size: Maximum 1MB for performance
  • Quality: High-quality images that represent the blog post content

Naming Convention: Use descriptive names that match your blog post:

  • trading-card-api-v040-release.jpg
  • getting-started-guide.png
  • best-practices-data-management.webp

2. File Organization​

Place all blog images in the /blog/images/ directory:

blog/
├── images/
│   ├── trading-card-api-v040-release.jpg
│   ├── getting-started-guide.png
│   └── best-practices-data.webp
├── 2025-09-11-trading-card-api-v040-release.md
└── 2024-08-29-getting-started-guide.md

3. Blog Post Configuration​

Add the image field to your blog post frontmatter:

---
title: Your Blog Post Title
authors: [tradingcardapi]
tags: [tag1, tag2]
description: Your blog post description
published: "2025-09-12 01:43:00"
image: your-featured-image.jpg
---

Note: The image field should contain only the filename (not the full path).

Features​

Responsive Design​

  • Desktop: Full-width hero images (400px height)
  • Tablet: Optimized height (300px)
  • Mobile: Compact view (200px height)

Performance Optimization​

  • Lazy loading for blog list images
  • Optimized image sizing
  • WebP format support

SEO & Social Media​

  • Automatic Open Graph meta tags
  • Twitter Card large image support
  • Proper alt text generation

Fallback Handling​

  • Posts without images display normally
  • No visual impact on existing posts
  • Graceful degradation

Examples​

---
title: Trading Card API v0.4.0 Release
authors: [tradingcardapi]
tags: [api, release, v0.4.0]
description: Major release with rate limiting and analytics
published: "2025-09-12 01:43:00"
image: trading-card-api-v040-release.jpg
---
---
title: API Best Practices
authors: [tradingcardapi]
tags: [best-practices, guide]
description: Guidelines for effective API usage
published: "2025-09-10 12:00:00"
---

Best Practices​

  1. Content Relevance: Choose images that directly relate to your blog post content
  2. Consistent Style: Maintain visual consistency across blog images
  3. Optimization: Compress images before adding to reduce file sizes
  4. Alt Text: Images automatically use blog post titles for alt text
  5. Preview Testing: Test social media previews before publishing

Technical Implementation​

The featured image system uses Docusaurus theme customization:

  • Blog List: /src/theme/BlogPostItem/index.js
  • Individual Posts: /src/theme/BlogPostPage/index.js
  • Styling: Responsive CSS modules for each component
  • Meta Tags: Automatic Open Graph and Twitter Card generation

Troubleshooting​

Image Not Displaying​

  1. Verify image exists in /blog/images/ directory
  2. Check filename matches exactly (case-sensitive)
  3. Ensure image format is supported (JPG, PNG, WebP)

Social Media Preview Issues​

  1. Images must be at least 1200x630px for optimal social sharing
  2. Clear social media cache after changes
  3. Test with social media preview tools

Performance Issues​

  1. Compress images to under 1MB
  2. Use WebP format when possible
  3. Ensure lazy loading is working on blog list

Migration​

Existing blog posts continue to work without modification. To add featured images:

  1. Add appropriate images to /blog/images/
  2. Update frontmatter with image: filename.jpg
  3. Test display on both blog list and individual post pages

This feature is fully backward compatible and optional.