Guides by the kind of help they give
Every guide on the site is one of four kinds, and the kind says what you will get before you open it. A how-to takes one task from start to finish with the configuration and the numbers it produced. A fix starts from something you can observe — a layout that jumps, a build that runs out of memory — and works back to the cause. A comparison puts two or more options side by side against criteria that were measured rather than asserted. A concept explains how something works and when it matters, without a single task at the end of it.
Pick the kind that matches the question in front of you. If you are deciding, start with comparisons and concepts; if you are doing, how-tos; if something is already wrong, fixes are filed under what you saw rather than what caused it.
How-tos
A task, end to end, with configuration and measured results.
- Accessible Code Blocks in Documentation SitesMake highlighted code blocks keyboard-scrollable, readable at AA contrast in both themes and labelled for screen readers, using Shiki, Prism or Hugo Chroma.
- Accessible Dark Mode Toggles for Static SitesBuild a theme toggle for a static site that follows the OS setting, has a real name and state, avoids a flash of the wrong theme and keeps AA contrast in both.
- Art Direction with the Picture ElementServe different crops of a hero image to mobile and desktop with picture and media queries in Astro, Eleventy and Hugo, without hurting LCP or causing layout shift.
- Auditing Font Payload per PageMeasure which fonts, weights and subsets each template of a static site really downloads, find unused faces and fallbacks, and set a font budget in CI.
- Accessibility Testing with axe and pa11y in CIRun axe-core through Playwright and pa11y-ci on sampled pages of a static site in both themes, fail pull requests on new violations and track the rest.
- Adding a Contact Form with Cloudflare WorkersBuild a contact form for a static site on Cloudflare: a Pages Function that validates, checks Turnstile, rate-limits, stores in D1 and emails the team.
Fixes
Starts from a symptom and ends at the cause and the fix.
- Fixing 404s on Refresh in Next.js Static ExportFix pages that work when navigated to but 404 on refresh or direct load in a Next.js static export, by matching file layout, trailing slashes and host rules.
- Fixing Astro Build Errors After Upgrading to Astro 5Work through the build errors an Astro 4 site hits on Astro 5, from legacy collections and slug to removed hybrid output, and prove the URLs did not change.
- CLS from Client-Side Rendered ComponentsStop islands and client-rendered widgets from shifting static pages: server-render the initial state, reserve space, and avoid content swaps after hydration.
- Debugging CLS with the Layout Instability APIFind the exact elements behind layout shifts on a static site with PerformanceObserver, attribution data from web-vitals and DevTools, then fix each shift.
- Finding the Cause of a Sudden Field LCP DropWork out why field LCP suddenly worsened on a static site: segment RUM data, line it up with deploys and third-party changes, and confirm the cause in the lab.
- Fixing Cold Starts in Netlify Functions for FormsMeasure and cut cold-start latency in a Netlify Function behind a static site's form: smaller bundles, lazy imports, regions and honest UI states.
Comparisons
Weighs two or more options against measured criteria.
- Astro vs Eleventy Build Times at 10,000 PagesAstro and Eleventy benchmarked on the same docs corpus from 1,000 to 10,000 pages: cold, warm and one-page-edit builds, memory, and where each scales badly.
- Astro vs Eleventy for Large Docs (1000+ Pages)A decision guide for documentation sites of 1000+ pages — comparing Astro and Eleventy on build scaling, search, MDX/components, and authoring ergonomics with measured numbers.
- Astro Islands vs Full Hydration PerformanceMeasured comparison of Astro islands against full SPA hydration — JavaScript bytes, Total Blocking Time, and INP numbers, plus which directive to reach for.
- Cloudflare vs CloudFront Cache Hit Ratios for Static SitesCloudflare and CloudFront measured serving the same static site: cache hit ratio, origin requests, TTFB by region and cost, plus the settings that moved each.
- Atomic Deploys vs Incremental UploadsWhy syncing files into a live bucket serves broken pages, how atomic publishing works, and how to build atomicity yourself on S3, object storage or a VM origin.
- Git-Based CMS Options for Static Sites ComparedDecap, TinaCMS, Sveltia, CloudCannon and Keystatic compared on one static site: editor experience, preview, Git workflow, setup effort, cost and lock-in.
Concepts
Explains how something works and when it matters.
- Best SSG for Non-Developer Technical WritersChoose an SSG for authors who avoid the terminal — prioritize a Git-backed visual editor, schema-validated frontmatter, and cloud CI that deploys on every commit.
- Choosing an SSG for API Reference DocumentationAPI docs are generated, versioned and enormous. Compare Hugo, Astro, Eleventy and Next export on build scale, schema-driven pages, versioning and search.
- Docs-as-Code Review Workflow for WritersBranch naming, small pull requests, preview-first review and a two-pass checklist — a docs-as-code process that non-engineers can follow and reviewers can sustain.