static-site-generation

This skill provides a structured methodology for engineering high-performance, content-centric websites using modern static site generation (SSG) frameworks. Designed for developers and technical writers, it facilitates the architectural decision-making process when choosing between frameworks like Astro, Next.js, and VitePress. The skill focuses on balancing strict hierarchical organization with flexible, networked content patterns, utilizing TypeScript for schema validation and MDX for rich, interactive documentation components.

• Framework evaluation and selection based on TypeScript support, MDX integration, and build performance metrics.

• Implementation of type-safe content collections using Zod schemas for structured data management.

• Standardized deployment workflows utilizing GitHub Actions and GitHub Pages for automated, zero-downtime releases.

• Configuration patterns for base paths, subpath hosting, and 404 error handling for single-page applications.

• Optimization strategies for bundle size, code splitting, and lazy loading to ensure fast initial page loads.

• Utilize the provided decision template to document architectural tradeoffs when choosing or migrating SSG frameworks.

• Follow the build optimization checklist before CI/CD deployment to ensure strict TypeScript compliance and correct asset path resolution.

• Inputs include markdown or MDX source files, Zod schemas, and framework-specific configuration files (e.g., astro.config.mjs).

• Outputs include production-ready static assets, validated content collections, and documented project structure.

• Constraint: Ensure all assets and routing paths are configured for GitHub Pages compatibility, specifically handling the site base path correctly.