Blog System

Blog pages for Engine Finder, featuring engine problem articles, guides, and category filtering.

Directory Structure

src/pages/blog/
├── index.astro                    # Main blog listing (page 1)
├── page/[page].astro              # Blog pagination (pages 2+)
├── [...slug].astro                # Individual blog post pages
└── category/
    ├── [category].astro           # Category listing (page 1)
    └── [category]/page/[page].astro  # Category pagination (pages 2+)

Key Files

File	Purpose
`src/content/blog/`	Blog post markdown files
`src/lib/blog/normalizeCategory.js`	Shared category normalization utility
`src/lib/constants.ts`	`BLOG_PAGINATION_SIZE = 12`
`src/components/PostCard.astro`	Blog post card component
`src/components/CategoryFilter.astro`	Category filter UI
`src/components/Paginator.astro`	Pagination component
`src/components/TableOfContents.astro`	Auto-generated table of contents

Category Normalization

Categories are normalized to consolidate brand variants (e.g., “Mercedes”, “Mercedes-Benz” → “Mercedes-Benz Engines”).

Shared utility: src/lib/blog/normalizeCategory.js

import { normalizeCategory } from '@/lib/blog/normalizeCategory';

This function is used by both [category].astro and [category]/page/[page].astro to ensure consistent category handling.

Pagination

Page size: 12 posts per page (defined in BLOG_PAGINATION_SIZE)
Page 1: Handled by main route (index.astro or [category].astro)
Pages 2+: Handled by pagination routes (page/[page].astro)

URL Structure

URL	Handler
`/blog`	`index.astro`
`/blog/page/2`	`page/[page].astro`
`/blog/category/audi-engines`	`category/[category].astro`
`/blog/category/audi-engines/page/2`	`category/[category]/page/[page].astro`

Static Generation

All blog routes use export const prerender = true; for static generation.

getStaticPaths Pattern

export async function getStaticPaths() {
  const allPosts = await getCollection('blog', ({ data }) => {
    const now = new Date();
    return data.draft !== true && new Date(data.pubDate) <= now;
  });
  // ... generate paths
}

Important: Posts are filtered by:

draft !== true - Draft posts are excluded
pubDate <= now - Future-dated posts are excluded

Blog Post Frontmatter

---
title: "Article Title"
description: "Article description"
pubDate: 2025-01-15
heroImage: "/images/blog/image.jpg"
categories: ["Engine Problems", "Audi Engines", "Maintenance"]
author: "Engine Finder"
featured: true
draft: false
slug: "problems/article-slug"
---

Table of Contents Feature

Every blog post automatically displays a Table of Contents that:

Extracts H2 and H3 headings from the markdown content
Generates anchor links for quick navigation
Collapsible on mobile (tap to expand/collapse)
Always visible on desktop
Includes smooth scrolling to sections
Positioned between ads and Key Takeaways box

Component: src/components/TableOfContents.astro

Implementation:

const { Content, headings } = await post.render();
// ...
<TableOfContents headings={headings} />

Styling:

Gradient background (gray-50 to gray-100)
Red accent icons and hover states
H2 headings: Bold with bullet points (•)
H3 headings: Indented with circle bullets (◦)
Scroll offset to account for sticky headers

Troubleshooting

404 on Blog Post

Check draft is false (not true)
Check pubDate is not in the future
Verify slug matches the file path

404 on Category Pagination

Ensure [category]/page/[page].astro exists
Check that normalizeCategory is imported from shared utility
Verify export const prerender = true; is set

ReferenceError: normalizeCategory is not defined

Import from shared utility: import { normalizeCategory } from '@/lib/blog/normalizeCategory';
Do NOT define inline in the Astro file frontmatter (scope issues with Vite)

Open Graph Meta Tags

Blog posts are configured with proper Open Graph meta tags for social media sharing (Facebook, LinkedIn, etc.).

Implementation: src/pages/blog/[...slug].astro

<Layout 
  title={post.data.title}
  description={post.data.description}
  canonical={`https://www.enginefinder.co.za/blog/${post.slug}/`}
  ogImage={post.data.heroImage ? `https://www.enginefinder.co.za${post.data.heroImage}` : 'https://www.enginefinder.co.za/images/mechanic-holding-engine.jpg'}
  ogType="article"
  publishedTime={post.data.pubDate.toISOString()}
  modifiedTime={post.data.updatedDate ? post.data.updatedDate.toISOString() : undefined}
  author="Craig Sandeman"
/>

Key Features:

Featured image (heroImage) is automatically used as the Open Graph image
Article-specific metadata (published time, modified time, author)
Full absolute URLs for images (required by Facebook)
Image dimensions (1200x630) specified for optimal rendering
Twitter Card support with large image preview

Testing Social Shares:

Use Facebook Sharing Debugger
Enter your blog post URL
Click “Scrape Again” to refresh Facebook’s cache
Verify the featured image, title, and description appear correctly

Layout Component

The Layout.astro component handles all Open Graph and Twitter Card meta tags:

<!-- Open Graph -->
<meta property="og:title" content={title} />
<meta property="og:description" content={description} />
<meta property="og:image" content={ogImage} />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />
<meta property="og:type" content={ogType} />
<meta property="article:published_time" content={publishedTime} />
<meta property="article:author" content={author} />

<!-- Twitter Card -->
<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:image" content={ogImage} />

JSON-LD Structured Data

Blog posts include comprehensive JSON-LD structured data for enhanced SEO and rich snippets in search results.

Schemas Included:

BlogPosting Schema - Article metadata, author, publisher, dates
BreadcrumbList Schema - Navigation hierarchy (Home > Blog > Category > Post)

Implementation: src/pages/blog/[...slug].astro

<!-- JSON-LD Structured Data for BlogPosting -->
<script type="application/ld+json" set:html={JSON.stringify(blogPostingSchema)} />

<!-- JSON-LD Structured Data for BreadcrumbList -->
<script type="application/ld+json" set:html={JSON.stringify(breadcrumbSchema)} />

Key Features:

Properly escaped JSON strings using set:html directive
ISO 8601 date formatting for published/modified dates
Automatic category extraction for breadcrumb hierarchy
Graceful handling of optional fields (e.g., updatedDate)
Full absolute URLs for all resources

Testing Structured Data:

Use Google’s Rich Results Test
Enter your blog post URL
Verify BlogPosting and BreadcrumbList schemas are detected
Check for validation errors or warnings

Schema Properties:

BlogPosting:

headline - Post title
description - Post description
image - Featured image URL
datePublished - Publication date (ISO 8601)
dateModified - Last updated date (falls back to pubDate if not set)
author - Organization entity (Engine Finder)
publisher - Organization with logo
mainEntityOfPage - Canonical URL

BreadcrumbList:

Position 1: Home
Position 2: Blog
Position 3: Primary category (from first category in frontmatter)
Position 4: Current post title

Callout Boxes

Blog posts support 5 types of styled callout boxes to display data attractively within markdown content.

Available Callout Types

Type	Color	Use For	Icon
Did You Know	Blue	Facts, statistics, reliability ratings	💡
Pro Tip	Green	Maintenance advice, diagnostic tips	✅
Warning	Orange	Safety alerts, expensive mistakes	⚠️
Forum Insight	Purple	Owner experiences, community quotes	💬
Statistic	Red	Percentage data, key numbers	Large number

Usage in Markdown

<div class="callout callout-did-you-know">
  <div class="callout-icon">💡</div>
  <div class="callout-content">
    <strong>Did You Know?</strong>
    <p>The BMW N52 has a 73% reliability rating.</p>
    <cite>Source: Consumer Reports 2023</cite>
  </div>
</div>

Features

Gradient backgrounds with color-coded borders
Hover effects (shadow intensifies)
Responsive (stacks vertically on mobile)
Works within Tailwind prose context
Citation styling for source attribution

Complete Documentation

See BLOG_CALLOUTS_GUIDE.md for:

All 5 callout types with examples
Copy-paste templates
Best practices and SEO considerations
Real article examples

Visual Examples

Open BLOG_CALLOUTS_EXAMPLE.html in browser to see all callouts rendered.

Implementation

Styles are in src/pages/blog/[...slug].astro (lines 488-612)

Content collection config: src/content/config.ts
Layout: src/layouts/Layout.astro
Callout boxes: BLOG_CALLOUTS_GUIDE.md