Blog System Documentation

This document provides a comprehensive guide to the blog system in Heatwave, covering content creation, SEO features, quality checks, and available plugins.

Table of Contents

1. Overview
2. Date Semantics
3. Content Structure
4. SEO & Structured Data
5. Liquid Tags (Plugins)
6. Quality Checks
7. Related Content
8. Comments System
9. Revision History
10. Feeds & Distribution
11. CRM Administration

---

Overview

Blog posts (Post model) are a specialized type of Article that support:

• Rich content with Liquid templating
• Structured data extraction (FAQ, HowTo schemas)
• Author attribution with bio pages
• Comments and engagement tracking
• SEO optimization tools
• Revision history and content versioning

Post States

State	Description
draft	Work in progress, not visible to public
published	Live on the website
scheduled	Will auto-publish at publish_on date
archived	Removed from public view

---

Date Semantics

The blog system uses three distinct date fields with specific meanings:

Field	Purpose	Public Display
published_at	Original publication date	Always shown in feeds/schema
revised_at	Substantial content revision	Shown as “last updated” when present
updated_at	Internal tracking (any edit)	Never shown publicly

Display Rules

1. Blog post page:

   • If revised: “last updated [revised_at]”
   • If not revised: “published on [published_at]”
   • Note: Original publication date is preserved in JSON-LD/Atom for SEO but not shown visually

2. Blog listings: Show revised_at if present, otherwise published_at

3. Atom feed:

   • <published>: Always published_at
   • <updated>: revised_at if present, otherwise published_at

4. JSON-LD BlogPosting:

   • datePublished: Always published_at
   • dateModified: revised_at if present, otherwise published_at

5. Open Graph meta tags:

   • article:published_time: Always present
   • article:modified_time: Only present when revised_at is set

Setting Revision Date

In the CRM editor:

• Manual: Set the “Revised at” date picker
• Automatic: Check “Automatically update revised at” when saving (updates to current time)

---

Content Structure

Core Fields

Field	Description	Character Limit
subject	Main title (H1 on page)	70 characters
title	Page title (browser tab)	65 characters
description	Summary/excerpt	No limit (keep concise)
solution	Main content body (HTML/Liquid)	No limit
meta_description	SEO description override	160 characters recommended
meta_keywords	SEO keywords override	Optional

Breadcrumbs

Breadcrumbs provide context for where the blog post fits in the site hierarchy.

Format options:

• Simple path: /floor-heating
• With custom title: Radiant Floor Heating@/floor-heating

Rules:

• Must start with /
• Auto-sorted by specificity (general → specific)
• First public tag used if no breadcrumb defined

Tags

Tags categorize blog posts. Public tags appear in the URL structure.

Public tags (appear in navigation):

company-news, countertop-heaters, design-trends, example-projects,
general-information, heat-tape-for-pipes, indoor-heating, installation,
led-mirrors, mirror-defoggers, outdoor-heating, press-industry-report,
press-release, product-information, radiant-floor-heating, radiant-panels,
remodeling, roof-and-gutter-deicing, troubleshooting, share-your-story,
shower-kits, snow-melting, towel-warmers, trade-professionals

---

SEO & Structured Data

Automatic Schemas

The system automatically generates:

1. BlogPosting (via PostPresenter)

   • Title, description, author (Person with profile URL when available, else display name, else publisher org)
   • Publisher (Organization), inLanguage
   • datePublished and dateModified
   • wordCount (integer, schema.org camelCase), article body, featured image

2. Breadcrumb (via formatted_breadcrumb helper)

   • One JSON-LD BreadcrumbList per page. Blog show renders breadcrumb only inside _post.html.erb (a duplicate hidden breadcrumb was removed — it had caused two identical BreadcrumbList blocks).

AI-Extracted Schemas

The BlogSchemaExtractor service uses AI (GPT-4) to extract:

Schema Type	When Extracted
FAQPage	Q&A content (unless embedded FAQ exists)
HowTo	Step-by-step instructions, tutorials

Note: Article/BlogPosting schemas are NOT extracted (already handled).

Manual Schema Markup

In the CRM “Advanced” tab, you can add custom JSON-LD:

[
  { "@type": "FAQPage", "mainEntity": [...] },
  { "@type": "HowTo", "name": "How to Install...", "step": [...] }
]

Meta Tags Generated

<meta property="article:published_time" content="...">
<meta property="article:modified_time" content="..."> <!-- Only if revised -->
<meta property="article:author" content="...">
<meta property="article:section" content="...">
<meta property="article:tag" content="...">
<meta property="og:updated_time" content="..."> <!-- Only if revised -->

---

Liquid Tags (Plugins)

Available Liquid tags for blog content:

1. FAQ Tag

Embeds FAQ with inline JSON-LD schema.

{% faq 1234 %}
{% faq 1234,5678,9012 %}

2. Video Tag

Embeds a video player.

{% video 123 %}

3. Cloudflare Video

Embeds Cloudflare Stream video.

{% cloudflare_video abc123def %}

4. Image Tag

Responsive image with proper sizing.

{% image 456 width:800 alt:"Description" %}

5. Floor Heating Calculator

Interactive calculator widget.

{% floor_heating_calculator %}

6. Snow Melting Calculator

Interactive snow melt calculator.

{% snow_melting_calculator %}

7. Partial

Include shared content partials.

{% partial "shared/cta_block" %}

---

Quality Checks

Page Title Validation

• Maximum 65 characters
• Displayed with check/ban icon in CRM

Content Processing Options

Option	Description
Sanitize URLs	Fixes broken links, adds https scheme
Sanitize HTML	Cleans inline styles, adds Bootstrap classes
Auto-update revised_at	Updates revision date on save

Table of Contents

Enable has_toc to auto-generate navigation from headings:

• Default selector: h2
• Custom selector via toc_selector field

SEO Panel

The CRM shows an SEO overview panel with:

• Site visits (30 days)
• Ranking keywords count
• Health score (AI-generated)
• Quick links to locale-specific SiteMap details

---

Related Content

Manual Related Posts

Specify up to 4 related posts in the CRM editor.

Automatic Suggestions

The system uses semantic embeddings to find similar content:

• Based on title, body, and product associations
• Product context from breadcrumbs

---

Comments System

Blog posts support moderated comments:

• Comments stored in post_comments table
• Accessible via post.post_comments
• Count displayed in CRM
• Moderation interface at /posts/:id/post_comments

---

Revision History

Published posts support content revisions:

1. Automatic versioning on significant edits
2. Preview any historical revision
3. Restore to previous version (creates new revision)
4. Change notes for audit trail

Access via CRM post show page “Revision History” panel.

---

Feeds & Distribution

Atom Feed

Available at /posts.atom

• Paginated with next/prev links
• Entry includes full content
• Proper published and updated timestamps

Referral Tracking

Each post auto-generates a Source for referral tracking:

• Short URL via Bitly
• Short URL with referral code
• Source analytics integration

Edge Cache

Posts integrate with Cloudflare edge caching:

• Auto-purge on publish/update
• Tag-based bulk purging available
• Purges related pages (index, tag pages)

---

CRM Administration

Post Editor Tabs

Tab	Contents
Summary	Title, author, dates, preview image
Content	Rich text editor (TinyMCE)
Tagging	Breadcrumbs, tags, meta fields
Related	Up to 4 related post links
Advanced	Content processing, TOC, schema markup, inline JS
Product Lines	Associated products for context

Quick Actions

• Preview: View unpublished posts (token-based, 1-hour expiry)
• Publish/Unpublish: Change state
• Duplicate: Create copy as draft
• Extract Schema: Run AI schema extraction
• Purge Cache: Clear CDN cache

Bulk Operations

• Tag-based cache purge: Post.purge_all_posts_by_tag
• Schema extraction worker: BlogSchemaExtractionWorker
• Auto extraction: AutoBlogSchemaExtractionWorker

---

Best Practices

Content Quality

1. Title: Keep under 65 characters for full display in search results
2. Summary: Compelling excerpt that works as meta description
3. Images: Always include a preview image for social sharing
4. Breadcrumbs: Set appropriate context for SEO

SEO Optimization

1. Revision dates: Use for substantial updates, not typo fixes
2. Schema markup: Let AI extract, manually add only if needed
3. Related posts: Link to relevant content to reduce bounce
4. Tags: Use public tags for proper categorization

Content Freshness

1. Review and update evergreen content periodically
2. Set revised_at when making substantial updates
3. This signals freshness to search engines and users

---

Technical Reference

Model: Post < Article

Key associations:

belongs_to :preview_image, class_name: 'Image', optional: true
belongs_to :source, optional: true
belongs_to :original_author, class_name: 'Employee', optional: true
has_many :post_comments, dependent: :destroy
has_many :site_maps, as: :resource

Key methods:

post.effective_published_date  # published_at || created_at
post.effective_revised_date    # revised_at || published_at
post.primary_tag               # First tag
post.main_public_tag           # First public tag
post.content_for_embedding     # Text for semantic search

Related Services

Service	Purpose
BlogSchemaExtractor	AI-powered schema extraction
PostPresenter	View presentation logic, JSON-LD generation
BlogPreviewTokenService	Secure preview URLs
Sitemap::SitemapGenerator	XML sitemap integration

---

Last updated: January 2026