blog-builder

---
name: blog-builder
description: >
  Guide for quickly setting up a personal blog from scratch. Covers framework selection
  (Hugo, Hexo, Astro, Next.js), theme configuration, blog post template generation with
  frontmatter, deployment to GitHub Pages / Vercel / Cloudflare Pages, and full SEO setup
  (sitemap, robots.txt, Open Graph, canonical URLs).

  Use this skill whenever the user mentions: setting up a blog, static site, personal site,
  portfolio, or asks about Hugo / Hexo / Astro blog setup, choosing a blogging framework,
  deploying a blog, or configuring SEO for a blog. Trigger even if they just say "I want a blog"
  without specifying a framework.
---

# Blog Builder

Help the user launch a personal blog -- from picking a framework through to live deployment with
proper SEO. Full scope: framework choice -> theme -> post template -> deploy -> SEO.

## Workflow

### Step 1 -- Understand the user context

Ask (or infer from context):
- Technical background? (non-technical / JS dev / Python dev / etc.)
- Starting fresh or have an existing site?
- Preferred deploy target: GitHub Pages, Vercel, Cloudflare Pages?
- Content focus: writing, portfolio, tutorial blog, docs?

### Step 2 -- Recommend a framework

| Situation | Recommended |
|-----------|------------|
| Non-technical, just wants to write | **Hugo** -- zero JS, fast, huge theme library |
| Already writes JS/TS, wants component control | **Astro** -- islands architecture, great DX |
| Loves theme ecosystems, Node-comfortable | **Hexo** -- mature plugin ecosystem |
| React dev, wants full control | **Next.js** -- App Router + MDX |

Present the recommendation with a short rationale. Confirm before proceeding.

### Step 3 -- Framework setup

Read the relevant reference file and walk the user through installation + a starter theme:

| Framework | Reference file |
|-----------|---------------|
| Hugo | references/hugo.md |
| Hexo | references/hexo.md |
| Astro | references/astro.md |
| Next.js | references/nextjs.md |

### Step 4 -- Generate a post template

Produce a ready-to-use post template file with complete frontmatter.
Asset templates in assets/post-templates/ are starting points -- copy and adapt to the
user's chosen theme and preferences.

### Step 5 -- Deployment

Read references/deployment.md for the appropriate CI/CD workflow. Provide the complete
GitHub Actions YAML, ready to commit.

Key notes:
- GitHub Pages: push to .github/workflows/deploy.yml; enable Pages in repo settings
- Vercel: connect repo in dashboard; set framework preset and output dir
- Cloudflare Pages: build command = npm run build, output dir = dist (Astro/Hexo/Next.js)
  or public (Hugo)

### Step 6 -- SEO configuration

Every blog needs:
1. sitemap.xml -- framework-specific; see references/<framework>.md
2. robots.txt -- provide actual file content, not just a description
3. Open Graph tags -- og:title, og:description, og:image, og:url as actual markup
4. Canonical URLs -- set baseURL / site in config so sitemaps and OG tags work correctly

Always note: the site URL must be set in the framework config for the sitemap to generate
correct absolute URLs.

## Guiding principles

- Provide actual file content (code, YAML, TOML), not just descriptions
- Include only the fields that matter -- avoid overwhelming boilerplate
- Point out the one or two gotchas that trip people up (e.g., Hugo baseURL, Astro site field)
- Prefer copy-paste-ready examples