# Blog Template Best Practices **Last Updated:** 2026-01-10 Validated best practices for blog template development, cross-referenced with Ordio patterns and industry standards for SEO, performance, accessibility, and user experience. ## Overview This document consolidates best practices for blog template development, validated against industry standards and cross-referenced with existing Ordio patterns from templates, product pages, and homepage. ## SEO Best Practices ### Meta Tags **Title Tags**: - **Length**: Max 60 characters (Google truncates at ~60) - **Pattern**: `{Post Title} | {Category} | Ordio` - **Include**: Year if relevant, primary keyword, brand name - **Uniqueness**: Every page must have unique title - **Example**: `Leitfaden zur Finanzbuchhaltung | Lexikon | Ordio` **Meta Descriptions**: - **Length**: 155-160 characters (optimal for SERP display) - **Tone**: Du tone (informal "du") - **Content**: Benefit-driven, include primary keyword naturally - **Uniqueness**: Every page must have unique description - **Example**: `Leitfaden zur Finanzbuchhaltung: Hier erfährst du alles, was du zum Thema wissen musst. Behalte deine Finanzen im Griff. Jetzt reinlesen!` **Canonical URLs**: - **Format**: Absolute URLs, HTTPS - **Pattern**: Match actual page URL exactly - **Purpose**: Prevent duplicate content issues - **Example**: `https://www.ordio.com/insights/lexikon/leitfaden-zur-finanzbuchhaltung/` **Open Graph Tags**: - **Required**: `og:title`, `og:description`, `og:url`, `og:type`, `og:image` - **Type**: `article` for posts, `website` for index - **Image**: 1200x630px recommended, WebP format - **Locale**: `de_DE` for German content **Twitter Card Tags**: - **Card Type**: `summary_large_image` - **Labels**: "Written by", "Est. reading time" - **Image**: Same as OG image **Robots Meta**: - **Index Pages**: `index, follow, max-image-preview:large, max-snippet:-1, max-video-preview:-1` - **Category Archives**: `noindex, follow` (current WordPress pattern) ### Heading Hierarchy **Critical Requirements**: - **Post Title**: Displayed as H1 in `PostHeader.php` component - **Content Headings**: Must start with H2 (never H1, H3, or H4 as first heading) - **Sequential Hierarchy**: H2 → H3 → H4 (no skipping levels) - **No Backwards Hierarchy**: Never go backwards (e.g., H3 → H2 is invalid) - **Semantic Structure**: Headings should reflect content structure, not just styling **Best Practices**: - **First Heading**: Always H2 (post title is H1) - **Main Sections**: Use H2 for top-level sections - **Subsections**: Use H3 for subsections under H2 - **Sub-subsections**: Use H4 for subsections under H3 - **Maximum Depth**: Generally avoid going deeper than H4 - **Consistency**: Maintain consistent hierarchy throughout post **Common Issues to Avoid**: - ❌ Starting content with H3 or H4 (should be H2) - ❌ Backwards hierarchy (H3 → H2) - ❌ Skipped levels (H2 → H4 without H3) - ❌ All headings at same level when they should be hierarchical **Validation**: - Use `v2/scripts/blog/analyze-heading-hierarchy.py` to analyze all posts - Use `v2/scripts/blog/validate-heading-fixes.py` to validate fixes - Fix issues with `v2/scripts/blog/fix-heading-hierarchy.py` **See**: `docs/content/blog/HEADING_HIERARCHY_GUIDE.md` for complete guidelines - **Single Posts**: `index, follow, max-image-preview:large...` ### Schema Markup **Required Schemas** (All Pages): - **Organization**: Company information, logo, social links - **WebSite**: Site-wide search action, publisher reference - **WebPage**: Page-specific metadata, breadcrumb reference **Page-Specific Schemas**: **Index Page**: - WebPage schema - BreadcrumbList schema **Category Archives**: - CollectionPage schema - ImageObject schema (primary image) - BreadcrumbList schema **Single Posts**: - Article schema (with author Person reference) - ImageObject schema (featured image) - BreadcrumbList schema - Person schema (author) **Schema Best Practices**: - Use JSON-LD format (preferred by Google) - Include all required fields for schema type - Use absolute URLs for all references - Validate with Google Rich Results Test - Ensure dates are ISO 8601 format - Include `@id` for cross-referencing ### Heading Hierarchy **Best Practices**: - **H1**: One per page (page/post title) - **H2**: Main sections (5-10 for most; 8-12 for main topics) - **H3**: Subsections (as needed) - **H4-H6**: Nested content (use sparingly) **Structure Example**: ``` H1: Post Title H2: Introduction Section H3: Subsection H2: Main Content Section H3: Subsection H2: Conclusion Section ``` **Accessibility**: Proper heading hierarchy improves screen reader navigation and SEO. ### URL Structure **Current WordPress Pattern**: - Index: `/insights/` - Category: `/insights/{category}/` - Post: `/insights/{category}/{slug}/` **Best Practices**: - Maintain current URL structure (SEO-friendly) - Use descriptive slugs (keywords, readable) - Avoid deep nesting (max 2-3 levels) - Use hyphens, not underscores - Lowercase URLs - No trailing slashes (or consistent) **Migration**: Preserve exact URLs to maintain SEO equity. ## Performance Best Practices ### Image Optimization **Format**: - **WebP**: Primary format (smaller file size, better quality) - **Fallback**: JPEG/PNG for older browsers - **SVG**: For icons and simple graphics **Responsive Images**: ```html Descriptive alt text ``` **Hero Images**: - Use `fetchpriority="high"` for LCP images - Preload critical hero images - Optimize file size (compress, WebP) **Content Images**: - Use `loading="lazy"` for below-fold images - Explicit width/height attributes (prevents CLS) - Responsive srcset for multiple sizes **Performance Targets**: - **LCP**: < 2.5s (Largest Contentful Paint) - **FID**: < 100ms (First Input Delay) - **CLS**: < 0.1 (Cumulative Layout Shift) - **PageSpeed Score**: > 90 (mobile and desktop) ### CSS Optimization **Loading Strategy**: - Critical CSS inline or preloaded - Non-critical CSS deferred (media="print" trick) - Minified CSS files (.min.css) - Cache busting with filemtime() **Pattern**: ```php ``` **Best Practices**: - Use Tailwind CSS utility classes (existing pattern) - Minimize custom CSS - Remove unused CSS (tree shaking) - Use CSS containment for performance ### JavaScript Optimization **Loading Strategy**: - Defer non-critical scripts - Async for independent scripts - Minified JS files (.min.js) - No blocking scripts above fold **Pattern**: ```php ``` **Best Practices**: - Use Alpine.js for interactivity (existing pattern) - Minimize JavaScript bundle size - Code splitting for large apps - No console.log/error/warn statements (use structured logger) ### Caching Strategy **Static Assets**: - Long cache headers (1 year) - Versioned filenames (cache busting) - CDN caching **HTML Pages**: - Short cache (1 hour) - Revalidation on content update - CDN edge caching **Implementation**: - Use `filemtime()` for cache busting - Set appropriate cache headers - Use CDN for static assets ## Accessibility Best Practices ### Semantic HTML **Required Elements**: - `
` for blog posts - `