# SW Blog Listing Hero — AI Agent Documentation

**Module path:** `smithworks-2025/sw-modules/SW Blog Listing Hero.module`  
**Last updated:** 2026-02-14

---

## 1. Overview

SW Blog Listing Hero is the hero section on **blog listing** pages (main blog index, tag pages, author pages). It shows a featured post’s image, title, metadata (tags, author, date), optional summary, and a Read More button. It uses the most recent post from the listing or a selected post.

**Where it’s used:** Only on **blog listing** templates (e.g. SW Blog Listing). It is not used on blog post pages (use SW Blog Post Hero) or website/landing pages (use SW Simple Hero).

---

## 2. Hero Configurations

- **Banner Image Above** — Image above content; stacked layout.
- **Banner Image as Background** — Image as full-bleed background; content overlays.
- **Pillar Section Style** — Two-column layout (image left, content right).

### Vertical position of the text box (Banner Image as Background)

The vertical position of the text box overlay is controlled by:

1. **Module Settings > Spacing** — Padding (especially **bottom padding**) adds space around the module content. Default bottom padding is 50px. Use this to fine-tune how far the text box sits from the bottom of the hero.
2. **Module Settings > XL Module Height > Vertical Alignment** — Top, Middle, or Bottom. Controls where the text box sits within the hero area (top, center, or bottom). Default: Bottom.

---

## 3. Post Source

- **Data** — Optional. Select a specific blog post to feature. When blank, uses the most recent post from the listing (`contents[0]`).
- **Show only on first page** — When enabled, the hero is hidden on paginated listing pages (page 2+).

---

## 4. Configuration Reference

### Content Tab

- **Custom ID** / **Custom Classes** — Optional.
- **Enabled** — Toggle module on/off.
- **Show only on first page** — Hide hero on page 2+ of listing.
- **Data** — Page picker; select post to feature (blank = most recent).
- **Tags** — Show/hide post tags. When shown, tags appear **below the heading** with a divider (·), matching SW Blog Post Hero and Post Body (not as buttons).
- **Text before tags** — Label before the tag list (e.g. "Posted in:"). Visible when Tags is on.
- **Link tags to tag pages** — Toggle to link tags to their tag archive pages. Visible when Tags is on.
- **Post Heading** — Size, Display Size, Color for post title. The title does **not** link; it displays as plain text.
- **Show author** — Toggle author line on/off.
- **Text before author line** — Label before the author name (e.g. "Posted by:"). Matches SW Blog Post Hero and Post Body.
- **Include date** — Add " on [date]" to the author line.
- **Include time** — Add " at [time]" to the author line (only when Include date is on).
- **Show post summary** — Toggle summary on/off.
- **Lead text** — When summary is on, make the summary text larger (legacy; Content style overrides when set).
- **Content style** — When summary is on: Default, Large (text balanced), Large (text full-width), Small, Blockquote. Overrides Lead text when set.
- **Read More Button** — Enabled, Button Style (Primary, Secondary, Tertiary, Simple Link), Button Text, Link, Button Size, Add icon, Icon. Links to post URL.

### Style Tab

- **Module Settings** — Spacing, Max Module Width, XL Module Height (with Vertical Alignment for text box position), Layout, Container Width.
- **Module Background Settings** — Background Option (Blog Featured Image, Theme Color, Custom Color, Gradient, Image, Video); overlay, base color, playback toggles when Video.
- **Content Colors** — Text Color, Custom Text Color, Link Colors (theme_defaults, dark, light).
- **Blog Image Display** — Hero Configuration (Banner Image Above, Banner Image as Background, Pillar Section Style); Override Image Border Radius; Image Border Radius.
- **Text Box Settings** — Text Box Width (XL/LG/MD/SM), Text Box Side Spacing, Content Area Text Alignment (with tablet/mobile overrides), Text Box Padding, Border Radius, Background Color, Horizontal Alignment, Border.
- **Module Background Video** (Content tab, when Video selected) — Video Type, HubSpot Video, Video from files, External Embed, Poster image.

---

## 5. Related Modules

| Module | Use for |
|--------|---------|
| **SW Blog Post Hero** | Blog post template hero |
| **SW Simple Hero** | Website/landing page hero |
| **SW Blog Cards** | Blog listing cards below hero |

---

## 6. Hero Module Comparison

| Module | Use for | Page type |
|--------|--------|-----------|
| **SW Blog Listing Hero** | Featured post with image, title, metadata, summary, Read More | Blog listing (index, tag, author pages) |
| **SW Blog Post Hero** | Post's featured image, title, post meta | Blog post (single post) |
| **SW Simple Hero** | Heading, subheading, optional image, CTAs | Website/landing pages |

---

## 7. Document Version

**2026-02-16:** Content style option (summary). **2026-02-14:** Added AI documentation with sample demo; hero comparison table; configuration reference aligned with current fields (Show author, Text before author line, Include date, Include time; no avatar; Style tab: Module Settings, Module Background Settings, Content Colors, Blog Image Display, Text Box Settings).
**2026-02-13:** Initial documentation. Module cloned from SW Blog Hero; renamed for clarity. Custom ID/Classes; Read More button with Button Style and Button Size labels.