07 — BLOG SYSTEM

Depends on: 06_MODULE_SYSTEM.md · Next: 08_SECURITY.md

1. Choice: MDX Content Collections

Location: apps/web/content/blog/ (or blog/content/) — MDX with frontmatter
Why: Type-safe frontmatter, TOC, components in markdown, co-located images, SSG
Alternative: DB-backed BlogPost Prisma model — keep for admin-editable posts in Phase 3, but Phase 1 is file-based for simplicity

2. Folder & Image Convention

apps/web/content/blog/
├── understanding-url-shortening/
│   ├── index.mdx
│   ├── hero.webp       # 1200x630 OG
│   ├── cover.webp      # 800x450 card
│   └── thumb.webp      # 400x225 thumb
├── qr-codes-for-business/
│   ├── index.mdx
│   ├── hero.webp
│   └── ...
└── ... (5 in Phase 1, 50 by Phase 3)

Images committed, optimized with sharp, served via next/image, no external hotlinks.

3. Frontmatter Spec

---
title: "Understanding URL Shortening: The Complete Guide"
slug: "understanding-url-shortening"
description: "How URL shorteners work, when to use custom aliases, expiry, and analytics."
excerpt: "A practical guide to short links that actually convert."
author: "yas-team" # → authors/authors.json
publishedAt: "2026-08-07"
updatedAt: "2026-08-07"
category: "URL Shortening"
tags: ["links", "analytics", "seo"]
heroImage: "./hero.webp"
coverImage: "./cover.webp"
readingTime: 8 # minutes, auto if missing
featured: true
related: ["qr-codes-for-business", "custom-aliases-seo"]
faq:
  - q: "Do short links hurt SEO?"
    a: "No — 301/302 preserves equity when canonical is set."
seo:
  title: "URL Shortening Guide — yas.sh"
  description: "How short links work + best practices."
  keywords: ["url shortener", "custom alias"]
---

Validation: content-collections or velite Zod schema at build — fail on missing required fields.

4. Rendering Requirements

Auto TOC from H2/H3 (rehype)
Author bio box (from authors.json)
3+ related posts + ≥4 internal links per article
Article JSON-LD (Article schema) + BreadcrumbList
readingTime, publishedAt/updatedAt visible
Code blocks with copy button + language tabs when API examples present
Ends with genuine CTA (not filler)

5. Quality Bar Per Article

Length: 1,200–2,200 words
Structure: H2/H3, skimmable, no keyword stuffing
Accuracy: Technically correct (reviewed), zero lorem ipsum
SEO: Unique slug, SEO title/description, canonical, OG image (generated), canonical URL
Perf: SSG, image optimized, LCP <1.8s

6. Index & Discovery

/blog — paginated (12 per page), filter by category/tag/author
/blog/category/[slug], /blog/tag/[slug], /blog/author/[slug]
/blog/rss.xml — RSS 2.0
Search: MariaDB full-text on title/excerpt (Phase 1); Meilisearch later
sitemap.xml includes every published slug (regenerated on build)

7. Phase 1 — 5 Production Articles

#	Slug	Title	Category	Image Prompts Included
1	`understanding-url-shortening`	Understanding URL Shortening: The Complete Guide	URL Shortening	Minimal link illustration, indigo
2	`qr-codes-for-business`	QR Codes for Business: From Scan to Conversion	QR / Marketing	QR scan in retail
3	`custom-aliases-seo`	Custom Aliases & SEO: Short Links That Rank	SEO	Alias vs random code comparison
4	`link-analytics-explained`	Link Analytics Explained: What to Measure	Analytics	Dashboard chart abstract
5	`api-keys-best-practices`	API Keys Best Practices for Developers	Developers	Key + shield abstract

Each → full MDX (1,500+ words), hero/cover/thumb .webp, SEO + JSON-LD + FAQ + TOC.

Additional 45 articles (to reach 50) are listed with stubs in 14_PRODUCT_SPECIFICATION.md and blog/content/_stubs/ with title/slug/category/tags so roadmap is visible, but only 5 are fully rendered in Phase 1.

8. Author System

content/authors.json:

{ "yas-team": { "name": "YAS Team", "role": "Engineering", "avatar": "/authors/yas.webp", "bio": "..." } }

Next: 08_SECURITY.md — defense in depth.

07_BLOG_SYSTEM