Blog Template Builder

---
name: blog-template-builder
description: Use when generating a blog post template or listing index — typography, code blocks, callouts, TOC, related posts. Triggers on "blog template", "blog post layout", "blog index page".
---

# Blog Template Builder

Build blog templates that respect the reader. Most defaults fail because line length is too long (90+ characters), code blocks overflow, headings don't have clear hierarchy, and there's no TOC for long posts. Fix all of that.

## Required inputs

1. **Framework** — Astro (best for MDX content sites), Next.js MDX, or vanilla HTML
2. **Content source** — local MDX files, headless CMS, or RSS feed
3. **Length expectation** — short (< 1000 words) vs long-form (3000+) — drives TOC decision
4. **Code-heavy?** — affects syntax highlighting choice (Shiki for build-time, Prism for runtime)
5. **Branding** — accent color, optional custom font

## Output format

```
src/
  layouts/
    BlogLayout.astro
  components/
    blog/
      Callout.astro
      CodeBlock.astro
      Toc.astro
      AuthorCard.astro
      RelatedPosts.astro
  pages/
    blog/
      index.astro       // listing
      [...slug].astro   // post
  content/
    blog/
      *.mdx
```

For Next.js: `app/blog/page.tsx` (listing), `app/blog/[slug]/page.tsx` (post), `mdx-components.tsx` for custom components.

## Post layout structure

1. **Header**
   - H1 title (`text-4xl md:text-5xl font-semibold tracking-tight`)
   - Subtitle / dek (`text-xl text-gray-600`)
   - Metadata row: author avatar, name, date, read time, tags
2. **Hero image** (optional) — full-bleed or constrained, with caption
3. **TOC** (only if 1500+ words) — sticky on the side at `lg+`, inline at top below header on mobile
4. **Body** — prose styling
5. **Footer block**
   - Author bio card
   - Related posts (3 cards)
   - Newsletter signup (optional)
6. **Comments** (optional) — Giscus / Disqus / nothing

## Typography (the actual important part)

```
.prose {
  max-width: 68ch;          /* ~65-75 chars per line */
  font-family: 'Inter', system-ui, sans-serif;
  font-size: 1.125rem;      /* 18px on desktop */
  line-height: 1.7;
  color: theme('colors.gray.800');
}
.prose h2 { font-size: 1.875rem; line-height: 1.3; margin-top: 3rem; margin-bottom: 1rem; }
.prose h3 { font-size: 1.5rem; line-height: 1.35; margin-top: 2rem; margin-bottom: 0.75rem; }
.prose p { margin: 1rem 0; }
.prose a { color: theme('colors.indigo.600'); text-decoration: underline; text-underline-offset: 3px; }
.prose blockquote { border-left: 4px solid theme('colors.gray.300'); padding-left: 1rem; font-style: italic; }
```

Use Tailwind's `@tailwindcss/typography` plugin (`prose prose-lg`) — it's tuned. Override what you don't like.

## Code blocks

Default to **Shiki** (build-time syntax highlighting via `shiki` or `rehype-pretty-code`). Outputs themed HTML, no client JS.

Block features:
- Language label in the corner (`bash`, `tsx`, `python`)
- Optional filename header (`<figcaption>app/page.tsx</figcaption>`)
- Line numbers (off by default; on for long blocks)
- Highlight specific lines via metadata (`\`\`\`tsx {3,5-7}`)
- Copy button (small, top-right) — JS-only enhancement
- `overflow-x-auto` so wide lines scroll horizontally, never wrap

Inline code: `text-sm font-mono bg-gray-100 px-1.5 py-0.5 rounded`. NOT colored — distinguishes from links.

## Callouts

Three variants: `info` (blue), `warning` (amber), `danger` (red).

```
<aside role="note" class="my-6 rounded-lg border-l-4 border-amber-500 bg-amber-50 p-4">
  <p class="font-semibold text-amber-900">Heads up</p>
  <p class="mt-1 text-amber-900">{content}</p>
</aside>
```

In MDX: `<Callout type="warning">...</Callout>`. Type-driven styling.

## Table of contents

For long posts only. Generated from H2/H3 (skip H1 — that's the title).

- Sidebar position on `lg:` screens (`sticky top-24`)
- Inline above content on mobile (collapsible)
- Highlight the current section as user scrolls (IntersectionObserver)
- Smooth scroll on click; focus the heading after navigation (a11y)

## Listing page

```
[Title] [Date] [Tags]
[Excerpt — 2 lines max]
[Read more →]
```

- 10-15 posts per page, then paginate
- Tag filter at top (`<select>` or pill row)
- Featured post optional at top (larger card)
- RSS link in the page header (and `<link rel="alternate" type="application/rss+xml">` in `<head>`)
- OG image per post if you have one

## Related posts

3 cards. Tag-overlap or content-similarity. If you have neither, show 3 most-recent excluding the current post.

## Accessibility

- `<article>` wraps the post; `<aside>` for TOC and callouts
- Heading hierarchy: one `<h1>` (title), then `<h2>` for sections, never skip levels
- Code blocks: `<pre><code class="language-tsx">` semantics; copy button has `aria-label="Copy code"`
- Focus-visible on every link
- Skip-to-content link
- `prefers-reduced-motion`: skip the smooth scroll if requested

## SEO

- `<title>`: `{post.title} – {Brand}`
- Meta description from post excerpt (155 chars)
- OG image: 1200x630, generated with the og-image-generator skill
- `<article itemscope itemtype="https://schema.org/BlogPosting">` if you care about structured data
- Canonical URL on every post

## Anti-patterns

- **Reading width 1200px+**: unreadable. Cap at 65-75ch.
- **`text-gray-500` body text**: too light, fails WCAG.
- **Code blocks that wrap**: scroll horizontally, never wrap (breaks indentation).
- **Auto-playing animations on scroll**: distracting; respect `prefers-reduced-motion`.
- **TOC on a 500-word post**: clutter. TOC is for posts with 5+ headings.
- **Comments on every post when nobody comments**: empty comment section reads as "nobody cares."

## Output

Return the layout, post template, listing template, and key components (Callout, CodeBlock, Toc). Top comment lists:
- Typography settings
- Syntax highlighter chosen
- TOC threshold (when it shows)
- Components exposed to MDX