static-site-generation

Framework evaluation criteria and deployment patterns for static site generators with GitHub Pages. Use when choosing SSG frameworks, configuring builds, or setting up GitHub Pages deployment.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026

When & Why to Use This Skill

This Claude skill provides a comprehensive technical framework for evaluating, configuring, and deploying Static Site Generators (SSGs) specifically optimized for GitHub Pages. It offers production-ready deployment patterns using GitHub Actions, critical configuration fixes for subpath hosting, and framework-specific comparisons (Astro, Next.js, VitePress) to streamline the transition from local development to automated production environments.

Use Cases

  • Framework Selection: Evaluating whether Astro, Next.js, or VitePress is the best fit for a project based on content needs, TypeScript support, and build performance.
  • Automated Deployment: Setting up robust CI/CD pipelines using GitHub Actions to automate the build and hosting process for static websites.
  • Configuration Troubleshooting: Resolving common 'broken asset' issues on GitHub Pages by correctly configuring base paths and 404 handling for subpath repositories.
  • Type-Safe Content Management: Implementing Content Collections with Zod schema validation to ensure data integrity in content-heavy documentation sites.
  • Build Optimization: Using a standardized checklist to verify TypeScript strict mode, asset pathing, and route generation before final deployment.
name"static-site-generation"
description"Framework evaluation criteria and deployment patterns for static site generators with GitHub Pages. Use when choosing SSG frameworks, configuring builds, or setting up GitHub Pages deployment."

Static Site Generation

Framework Evaluation Criteria

When evaluating SSG frameworks, prioritize:

  1. TypeScript support: First-class, not bolted-on
  2. MDX integration: Built-in or official plugin
  3. GitHub Pages compatibility: Base path support, static output
  4. Content collections: Type-safe content with schema validation
  5. Build performance: Fast rebuilds for iteration
  6. DX: Good error messages, debugging tools

Framework Comparison for Knowledge Base

Astro (Recommended for content-first sites)

  • Pros: Best MDX support, fast builds, content collections, multi-framework
  • Cons: Newer ecosystem, fewer community plugins
  • Best for: Documentation, knowledge bases, content-heavy sites

Next.js with Static Export

  • Pros: Huge ecosystem, familiar to React devs, mature tooling
  • Cons: Overkill for simple sites, larger bundles, requires explicit static config
  • Best for: Apps needing both static and dynamic capabilities

VitePress

  • Pros: Extremely fast, excellent docs focus, simple
  • Cons: Vue-specific, less flexible for complex needs
  • Best for: Pure documentation sites with minimal custom needs

Avoid: Gatsby (complex, slow builds, declining momentum)

GitHub Pages Configuration

Critical Settings

Base Path for Subpath Deployment:

// Required if deploying to github.io/repo-name/
export default defineConfig({
  site: 'https://username.github.io',
  base: '/repo-name/',  // Must include trailing slash
});

Output Directory:

  • Astro: dist/ (default)
  • Next.js: out/ (with output: 'export')
  • VitePress: .vitepress/dist/

404 Handling:

  • Create 404.html in output directory
  • For SPAs: All routes → 404.html (GitHub Pages limitation)

Deployment Pattern

Using GitHub Actions (Recommended):

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  deploy:
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run build
      - uses: actions/upload-pages-artifact@v3
        with:
          path: ./dist
      - uses: actions/deploy-pages@v4

Repository Settings:

  • Pages → Source: "GitHub Actions"
  • Branch deployment not needed with Actions

Build Optimization Checklist

Before marking build complete:

  • TypeScript strict mode enabled
  • Base path configured correctly
  • All routes generate static HTML
  • Assets use correct paths (relative to base)
  • 404 page exists
  • Build succeeds with zero errors
  • Deployment workflow tested

Content Collections Pattern

Define schemas for type-safe content:

import { z, defineCollection } from 'astro:content';

const docs = defineCollection({
  schema: z.object({
    title: z.string(),
    description: z.string(),
    date: z.date(),
    draft: z.boolean().default(false),
  }),
});

export const collections = { docs };

Benefits: Type safety, validation at build time, autocomplete in editor.

Common Pitfalls

Incorrect base path:

  • Symptom: Routes work locally, 404 in production
  • Fix: Ensure base matches repo name, includes trailing slash

Mixed path types:

  • Symptom: Some assets load, others don't
  • Fix: Use framework's path helpers consistently

Large bundle size:

  • Symptom: Slow initial load
  • Fix: Enable code splitting, lazy load heavy components

Missing TypeScript config:

  • Symptom: Type errors not caught during build
  • Fix: Enable strict mode, include all source files

Decision Template

When choosing framework, document in CLAUDE.md:

## Framework Decision: [Name]

**Chosen:** [Framework]
**Rationale:** [Why - 2-3 key reasons]
**Alternatives considered:** [What else, why not]
**Trade-offs:** [What we gain vs. lose]

Quick Start Validation

After framework initialization:

  1. Run build → Should succeed with zero errors
  2. Check output directory → HTML files present
  3. Test locally → npx serve dist → All routes work
  4. Deploy to GitHub Pages → All routes work with base path
  5. Check console → No 404s on assets