Fixes
A fix starts where you are: with something you can see. The page jumps as it loads. Lighthouse gives a different score on every run of the same commit. A build that used to finish in a couple of minutes now runs out of memory on the CI runner. Readers with a tab open across a deploy report that search stopped working. Each guide here names the symptom in its title, shows how to confirm which of the usual causes you actually have, and then fixes that cause — with the before and after numbers.
They are grouped by topic below. Layout-shift and LCP fixes dominate because those are the Core Web Vitals that static sites fail most often in the field while passing in the lab; the build-time fixes follow, and then the operational ones.
Accessibility for Static Sites
- Fixing Heading Order Problems in Markdown ContentFind and fix skipped heading levels, duplicate H1s and headings used for styling in Markdown, then lint for them in CI so the page outline stays usable.
- Fixing Low Color Contrast Flagged by LighthouseTrace Lighthouse and axe contrast failures on a static site back to a few design tokens, pick compliant replacements and keep them passing in both themes.
Astro vs Eleventy for Documentation Sites
- 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.
- Fixing Duplicate Permalink Errors in EleventyFind which templates produce the same output path in Eleventy, fix the usual causes in pagination, slugs and data files, and catch collisions in CI.
- Fixing Eleventy Out-of-Memory Errors on Large CollectionsDiagnose "JavaScript heap out of memory" in Eleventy builds of large collections, cut peak memory with data and template fixes, and size the Node heap safely.
- Fixing Slow Astro Builds Caused by Large MDX CollectionsFind why an Astro build with thousands of MDX files is slow, then convert plain pages to Markdown, trim plugins and cache the content layer in CI.
Docs Frameworks: Docusaurus, Starlight and VitePress
- Fixing Broken Links Reported by Docusaurus BuildsRead Docusaurus broken link and anchor reports, fix the common causes from relative paths to versioned docs, and make the build fail on new breaks.
Hugo Build Times for Large Repositories
- Fixing Hugo Builds That Fail After a Version UpgradeDiagnose Hugo build failures after an upgrade, from removed functions and pagination changes to output differences, then pin Hugo so it cannot recur.
- Fixing Hugo Builds That Slow Down After Adding TaxonomiesFind why a Hugo build got slower after adding tags or categories, then fix the term templates, related content and pagination that multiply the work.
- Reducing Hugo Memory Usage on CI RunnersWhy large Hugo builds run out of memory in CI, how to measure peak usage, and the settings, template changes and image strategies that cut it by more than half.
Internationalization for Static Sites
- Fixing Hreflang Errors Reported in Search ConsoleDiagnose missing return links, wrong language codes and non-canonical targets in hreflang on a static site, fix them in the templates, and test them in CI.
Jekyll Plugin Ecosystem
- Fixing Jekyll Builds That Break After a Ruby UpgradeFix the errors Jekyll sites hit on new Ruby versions, from missing webrick and stdlib gems to native extensions and date changes, then pin Ruby.
- Speeding Up Slow Jekyll BuildsProfile a slow Jekyll build, find the Liquid loops and plugins that dominate it, and apply caching and template fixes that cut build time by over 80%.
Migrating Between Static Site Generators
- Recovering Search Traffic Lost After a Generator MigrationFind why organic traffic dropped after moving to a new static site generator, from missing redirects to lost metadata, and recover it with measured steps.
Next.js Static Export for Content Sites
- 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.
Search for Static Sites
- Fixing Missing Results in Pagefind IndexesFind why pages or sections are missing from Pagefind search results, from data-pagefind-body scoping to build order and language, and verify the index in CI.
Technical SEO for Static Sites
- Fixing Pages Crawled but Not Indexed on Static SitesWork through Search Console's crawled but not indexed status on a static site: thin and duplicate pages, weak internal links and templates that hide content.
- Fixing Soft 404s on Static HostsFind and fix soft 404s on static sites, from SPA fallback rewrites and 200-status error pages to empty list pages, on Cloudflare, Netlify, S3 and Nginx.
CDN Caching Rules for SSGs
- Fixing Stale HTML After Deploys on CloudflareFind why readers see old pages after a deploy on Cloudflare, from Cache Everything rules and browser max-age to service workers, and fix each with a test.
CSS and JavaScript Asset Optimization
- Fixing Missing Tailwind Classes in Production BuildsFix styles that work locally but vanish in production with Tailwind: dynamic class names, unscanned files, Markdown content and safelists, plus a CI check.
- Fixing Unused JavaScript Warnings on Static PagesTrace Lighthouse's reduce unused JavaScript warning on a static site to its sources, from site-wide bundles to hydration and third parties, and fix each.
Cumulative Layout Shift Fixes for Static Sites
- 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.
- Eliminating Layout Shift From Web FontsKill font-swap CLS with size-adjust, ascent-override and a preloaded subset. Includes how to compute the override values and the measured 0.14 to 0.00 result.
- Fixing CLS From Dynamic Table of Contents WidgetsStop table of contents widgets built in the browser from shifting docs pages: render the list at build time, reserve the sidebar, and tame scroll-spy.
- Fixing CLS From Images Without Dimensions in MarkdownAdd width and height to every Markdown image at build time in Astro, Eleventy and Hugo, so images stop shifting content as they load, and check it in CI.
- Fixing CLS From Late-Loading EmbedsComment threads, video players, maps and consent banners land after paint and push the page around. Reserve their space at build time and take overlays out of flow.
- Fixing CLS from Cookie BannersConsent banners are a leading cause of layout shift on static sites. Overlay them, keep them compact, and keep the consent script off the critical path.
- Fixing CLS from Sticky Headers and Anchor LinksSticky headers that change height, shrink on scroll or hide anchor targets cause layout shift and lost headings. Fix them with fixed heights and scroll-padding.
Font Loading Strategies for Static Sites
- Fixing Invisible Text While Web Fonts LoadFind why text stays invisible while web fonts load on a static site, from missing font-display to icon fonts and CSS imports, and fix it without shift.
Image Optimization Pipelines in Astro
- Fixing Blurry Images From astro:assets ResizingFind why images from Astro's Image and Picture components look soft on high-density screens, and fix widths, sizes, densities and quality settings.
JavaScript Hydration & Partial Rendering
- Fixing Hydration Mismatch Errors in Astro IslandsTrack down hydration mismatch warnings in React, Preact and Vue islands on Astro pages, from dates to invalid HTML, and fix them without client:only.
- Fixing Poor INP on Static Pages With Heavy WidgetsFind which widget makes INP poor on an otherwise static page, then fix it with deferred hydration, yielding, lighter event handlers and smaller re-renders.
Largest Contentful Paint Optimization for Static Sites
- Eliminating Render-Blocking CSS on Static SitesInline critical CSS, defer the rest, and purge unused rules to cut render delay on static sites — with measured LCP and FCP before/after from Lighthouse.
- Fixing LCP Regressions Caused by Cookie Consent ToolsFind how a cookie consent tool delays LCP on a static site, from render-blocking scripts to banners becoming the LCP element, and fix it compliantly.
- Fixing LCP When the Hero Is a Background ImageWhen a hero is a CSS background image, the browser finds it late and cannot prioritise it. Move it to an img, or preload it, and measure the LCP difference.
- Fixing LCP on Text-Heavy Documentation PagesWhen the LCP element is a paragraph or heading, images are not the problem. Fix TTFB, render-blocking CSS and web fonts to speed up text-heavy docs pages.
- Fixing Slow LCP on Pages With Embedded VideoFix slow LCP on static pages with hero or embedded video: poster images as the LCP element, preloading, facades for YouTube and Vimeo, and lighter autoplay.
- Reducing LCP from Hero Images on Static SitesSize, format, and preload hero images to cut LCP on static sites — responsive srcset, AVIF/WebP, explicit dimensions, and why you must never lazy-load the hero.
Performance Budgets and Lighthouse CI
- Reducing Lighthouse Score Variance in CIWhy Lighthouse numbers jump between identical CI runs, and the six changes that shrank LCP spread from 800 ms to 90 ms so timing budgets can safely fail builds.
Resource Hints and Navigation Speed
- Fixing Wasted Preloads Flagged by ChromeDecode Chrome's preloaded-but-not-used and credentials-mode warnings, fix crossorigin, as and srcset mismatches, and remove stray generator preloads.
Third-Party Script Performance on Static Sites
- Fixing Main-Thread Blocking From Chat WidgetsMeasure how much main-thread time a support chat widget takes on a static site, then cut it with delayed loading, page targeting and a click-to-load launcher.
Cloudflare Pages Edge Caching Setup
- Fixing Redirect Loops on Cloudflare PagesDiagnose too many redirects on Cloudflare Pages, from SSL mode and trailing-slash rules to _redirects patterns and Page Rules, and fix each with a curl trace.
GitHub Actions for Automated SSG Builds
- Fixing Flaky Static Site Builds in GitHub ActionsTrack down static site builds that fail intermittently in GitHub Actions, from network fetches and cache races to memory limits and timing tests.
Incremental Builds and Build Caching for SSGs
- Fixing Stale Pages From Incremental BuildsFind why incremental builds leave some pages out of date, from untracked dependencies and global data to deleted files, and fix them without full rebuilds.
Monitoring Static Sites in Production
- 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.
Netlify vs Vercel Deployment Strategies
- Fixing Netlify Builds That Exceed the Time LimitDiagnose Netlify builds cancelled for exceeding the time limit, then cut build time with caching, skipped work and leaner dependency installs.
- Fixing Vercel Builds That Run Out of MemoryDiagnose static site builds killed for memory on Vercel, from heap limits and image concurrency to huge data files, and fix them on the same machine.
Preview Environments for Pull Requests
- Fixing Preview Deploys Leaking Into Search ResultsRemove preview and staging deploys from search results and stop new ones being indexed with X-Robots-Tag headers, canonicals, and removal requests per host.
Rollbacks and Deploy Safety for Static Sites
- Keeping Old Assets Alive After DeployStop open tabs from breaking after a static site deploy: keep previous hashed assets for days, handle chunk load errors, and clean up old files safely.
- Recovering From a Deploy That Deleted Live AssetsAn incident walkthrough: a sync with --delete removed hashed assets that cached HTML still referenced. How it was found, recovered in minutes and prevented.
Security Headers and Hardening for Static Sites
- Fixing Content Security Policy Violations From Inline ScriptsTrace CSP inline-script violations on a static site from reports to sources, then fix each with hashes, external files or removed handlers.
- Fixing Mixed Content Warnings After Moving to HTTPSFind every http:// reference in a static site's content, templates and data after moving to HTTPS, fix it at the source, and block new ones in CI.
Serverless Functions for Static Sites
- 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.
Testing Static Sites in CI
- Fixing Flaky Playwright Tests Against Preview DeploysStabilise Playwright tests that run against preview URLs: wait for the right deploy, warm caches, drop timing assumptions and isolate third parties.
Other kinds of guide
- How-tosA task, end to end, with configuration and measured results.
- ComparisonsWeighs two or more options against measured criteria.
- ConceptsExplains how something works and when it matters.