New researchTechnical SEO & AI Search · 2027Explore the framework

Static site SEO: a technical checklist for Astro and other generators

Static site generators ship no SEO defaults. Set up canonicals, the sitemap, redirects, 404s and hreflang yourself, and make the build fail on mistakes.

Part of the JavaScript SEO series. For the full picture, start with JavaScript SEO: the complete rendering and indexing guide.

Static site SEO is mostly a question of who makes each decision. On WordPress with an SEO plugin, on Shopify or on Webflow, the platform writes the canonical tag, builds the sitemap and creates a redirect when you change a slug. With Astro, Eleventy, Hugo or a static export from Next.js, the framework writes HTML and stops there. Every SEO rule is either in your code or nowhere.

That is a good trade. Static HTML arrives complete in the first response, with no rendering step between Google and your content (the JavaScript SEO guide explains why that matters). What you lose are the defaults. This checklist covers what to build yourself, the mistakes that keep coming up on static sites, and how to make the build catch them. The examples use Astro and Vercel, but the same rules apply to any generator and host. For the full Astro setup in code, follow the Astro SEO guide; to see which generator handles which SEO pieces for you, read Astro vs Next.js, Hugo and other generators.

What does a static site generator not do for SEO?

It doesn’t decide anything that depends on your intent: which URL is canonical, which pages stay out of search, where an old URL should go, or which pages are translations of each other. Here is what a typical platform handles and where it lives on a static site.

Task Typical platform Static site generator
Title, description, canonical, robots meta SEO plugin fills them in Written in your layout from page props
XML sitemap Built in, often with update dates An integration lists built pages; exclusions and dates are up to you
robots.txt Built in A static file or a generated route
Redirects after a URL change Created automatically or with a plugin Written by hand in the host’s config
404 status for unknown URLs Built in A 404 page you build; the host decides the status code
Trailing slash and one hostname Fixed by the platform Configured in both the framework and the host
Structured data Plugin output per content type JSON-LD you write per page type
hreflang Translation plugin Your own mapping between language versions
RSS, social images Plugin or theme Routes and image generation you add

None of this is hard. The risk is forgetting one piece, or making the same decision in two places that later drift apart.

Put every head tag in one layout

The single most useful rule: only one layout component writes SEO tags. Pages pass props (title, description, noindex, an image); they never add a canonical or robots meta of their own.

---
// src/layouts/Base.astro
const { title, description, noindex = false } = Astro.props
const canonical = new URL(Astro.url.pathname, Astro.site)
---
<html lang="en">
  <head>
    <title>{title}</title>
    <meta name="description" content={description}>
    {noindex
      ? <meta name="robots" content="noindex">
      : <link rel="canonical" href={canonical}>}
    {!noindex && <meta property="og:url" content={canonical}>}
    <slot name="head" />
  </head>
  <body><slot /></body>
</html>

Set site in astro.config.mjs. Astro’s configuration reference says it uses this value to generate your sitemap and canonical URLs, and Astro.site is empty without it.

Notice the either/or on the canonical. A page you keep out of search shouldn’t also declare itself the URL to index. Google’s guide to consolidating duplicate URLs describes rel="canonical" as a strong signal that a URL should be canonical, and its noindex documentation says a noindex page is dropped from Search entirely. Sending both on one page asks for opposite outcomes. When a page adds its robots meta through the head slot, the layout still prints the canonical, which is exactly how this conflict usually appears.

Checklist for the layout:

  • A self-referencing canonical on every indexable page, built from the URL, never typed by hand. Google recommends a canonical on the canonical page itself.
  • A noindex page gets a robots meta instead of a canonical, no og:url and no hreflang.
  • <html lang> matches the page’s language.
  • Exactly one <h1> per page, written by the page template.
  • A distinct title and description on every page. Google says there’s no limit on <title> length but the title link is truncated to fit the device, and it warns against repeated or boilerplate titles.
  • A social image per page, the same in og:image and twitter:image.
  • Facts that change (prices, version numbers, dates) read from data at build time, not typed into templates.

How do you set trailing slashes on a static site?

Pick one form and configure it in both the framework and the host. They are separate settings, and a mismatch creates duplicate URLs or redirect loops.

Google treats /page and /page/ as two URLs (the root URL is the exception). Its trailing-slash article recommends choosing a preferred form, redirecting the other one, and using the preferred form consistently in internal links and the sitemap.

In Astro, trailingSlash defaults to 'ignore'. The configuration reference says trailing slashes on prerendered pages are handled by the hosting platform and may not respect your setting. It suggests 'always' with the default build.format: 'directory' (which writes /page/index.html), or 'never' with build.format: 'file'.

On Vercel, "trailingSlash": true in vercel.json answers /about with a 308 to /about/ and leaves paths with a file extension alone, so /robots.txt and /sitemap-index.xml still work. With the setting undefined, both forms serve the same content without a redirect, which Vercel’s vercel.json reference itself says is not recommended because search engines could index both.

// astro.config.mjs
export default defineConfig({
  site: 'https://example.com',
  trailingSlash: 'always'
})
{
  "trailingSlash": true
}

Then make every internal link use the same form. A link to /pricing on a slash site works for visitors, but every crawl of it costs a redirect. Crawlens reports these as internal links that point to redirects.

Which redirects does a static site need?

A static host only redirects what you list. Four groups belong on almost every site:

Redirect Why Example rule
Other hostnames to the main one www, http and the host’s default domain all serve the site A host-based redirect to https://example.com
/index.html to the folder URL Static hosts serve the real file, so /blog/index.html answers next to /blog/ /:path+/index.html → /:path+/
Familiar file names Generators pick their own names (sitemap-index.xml), people and tools try /sitemap.xml /sitemap.xml → /sitemap-index.xml
Every removed or renamed URL No CMS creates them for you Old path → final destination, in one hop

On Vercel, "permanent": true sends a 308. Google’s HTTP status documentation says a 308 is equivalent to a 301 for Search, so either works. What matters more is that each redirect goes straight to the final URL. Normalisation rules that run one after another (HTTP to HTTPS, then hostname, then slash) are the classic source of redirect chains.

The default domain needs care on Vercel. Its guide to preview indexing says preview deployments get an X-Robots-Tag: noindex header automatically, but it doesn’t say the same for a production .vercel.app URL, and it suggests pointing search engines to one canonical address if that URL gets indexed. A host-based redirect to your domain settles it.

The trailing-slash trap in redirect patterns. A source like /old-section/:path* looks as if it matches everything under the old section. Test it against /old-section/ and /old-section too. If a variant slips through, use a pattern with an optional group, such as /old-section(/.*)?, and curl each form after deploying.

How do you make a static 404 page return a real 404?

Build the page, then let the host serve it for unknown paths, and don’t route around that. Astro builds src/pages/404.astro to 404.html, and its pages documentation says most deploy services will find and use it. The host decides the status code, so check it on the live site:

curl -s -o /dev/null -w "%{http_code}\n" https://example.com/this-page-does-not-exist/

The mistake to avoid is a rewrite or catch-all route that serves a “not found” page with status 200. That is a soft 404: Google’s status code documentation describes it as a page that looks like an error while the server returns a success code. It’s tempting on multilingual sites, where you want a translated 404 per language. Keep one real 404, and put links to each language’s home on it instead.

Keep the 404 page itself out of the sitemap and give it noindex.

How do you build an accurate sitemap on a static site?

Use the generator’s sitemap integration, then teach it the two things it can’t know: which pages are noindex, and when each page last changed.

Astro’s @astrojs/sitemap includes every built page by default and writes sitemap-index.xml plus numbered files such as sitemap-0.xml. Its documentation doesn’t mention noindex: pages are removed only through the filter option (return false to leave a URL out) or serialize (return undefined). So a noindex preview page ends up in the sitemap unless you exclude it.

sitemap({
  // Keep in sync with the pages that pass `noindex` to the layout.
  filter: (page) => !page.includes('/download/') && !page.includes('/preview/'),
  serialize: (item) => {
    const date = lastmodFor(new URL(item.url).pathname) // from front matter
    return date ? { ...item, lastmod: date } : item
  }
})

Two rules for the data:

  • The sitemap lists only indexable, canonical URLs. Google’s sitemap guide says to include the URL you prefer rather than every URL that leads to the same content. Crawlens flags violations as non-indexable URLs in sitemaps.
  • <lastmod> comes from content, not the build. Google uses it only when it is consistently and verifiably accurate, and only for significant changes. A static site rebuilds every page on every deploy, so the file time is useless. Take the post’s updated or date from front matter; give a listing the date of its newest entry; give pages with no content date no <lastmod> at all. The sitemap lastmod guide covers what counts as a significant change.

Skip changefreq and priority. Both the Astro docs and Google’s guide say Google ignores them.

The noindex filter is the weak spot: the list of noindex pages now lives in the layout props and in the sitemap config. Either generate both from one list, or check them against each other after the build (see the last section).

What about robots.txt, RSS and drafts?

  • robots.txt: a static file or a generated route that declares the sitemap. Don’t use it to remove pages from search. Google’s noindex documentation says a page blocked by robots.txt can’t have its noindex read, and that noindex in robots.txt isn’t supported. The noindex vs robots.txt guide explains when to use which.
  • Drafts: filter them in one function that every route uses, the post pages, listings, RSS feed, sitemap and any llms.txt. If each route reads the content collection on its own, sooner or later one of them forgets the filter and a draft goes live in the feed.
  • Feeds: generate RSS from the same filtered list, with absolute URLs in the preferred slash form.

How do you handle hreflang on a multilingual static site?

Keep one mapping of which pages are translations of each other, and generate everything from it: the <head> links, the language switcher and the sitemap alternates. Google’s localized versions guide sets the rules that mapping must satisfy:

  • Each version lists itself and every other version.
  • Links are reciprocal: if two pages don’t both point to each other, the tags may be ignored.
  • x-default names the fallback for users whose language matches no version.
  • URLs are fully qualified, including https://.
  • HTML tags, HTTP headers and sitemaps are equivalent, so pick one method or keep them generated from the same data.

Static sites tend to break these rules in predictable ways. A page that is translated in one language but still a draft in another gets an hreflang link to a URL that doesn’t exist. A noindex page appears in a translation group. The canonical of a translation points to the English page. Each of these is checkable in the built HTML, and Crawlens reports the live-site versions as hreflang without return links, hreflang to non-indexable URLs and missing x-default. The hreflang errors guide goes through the fixes.

Translations bring two smaller problems. Titles and descriptions get longer in some languages and can collide when a page is copied before it is translated. And links written by hand inside translated content keep pointing to the English page until someone updates them.

Structured data and social images

Write JSON-LD per page type in the template, not per page: BlogPosting with author and dates for posts, CollectionPage with an ItemList for listings, BreadcrumbList where you show breadcrumbs. Google’s structured data guidelines require the markup to describe content visible on the page and all required properties for a rich result type. Listing pages are easy to forget because they have no front matter of their own. The structured data errors guide covers validation.

If you render social images at build time, check the output in every language you publish. Image renderers draw text with the fonts you give them, and a font without the right glyphs shows boxes or drops accents silently. Ship full font files for each script you need.

Performance: keep a fast site fast

Static HTML starts with an advantage, so most performance work is about not adding weight:

  • Give every <img> width and height (or an aspect ratio) and real alt text.
  • Self-host fonts and preload only the files the first screen needs.
  • Load interactive JavaScript only on the pages that use it. Astro’s islands documentation says components render to HTML and CSS with client-side JavaScript stripped unless you add a client:* directive, so each script you ship is a choice.
  • Treat each third-party tag as a cost, and load analytics after consent where the law requires it.

Which mistakes come up most on static sites?

Almost every one of these comes from a decision made in two places, or a framework or host default that differs from what you assumed.

Mistake Why it happens Fix
Noindex page with a canonical Robots meta added through a head slot while the layout prints a canonical A noindex prop on the layout that replaces the canonical
Noindex page in the sitemap The sitemap integration lists every built page A filter, plus a post-build check against the robots meta
Mixed trailing slashes Framework and host configured separately; links written both ways Same setting in both; check internal links in the build
Redirect misses the slash form /old/:path* doesn’t match every variant An optional group such as /old(/.*)?; curl both forms
/index.html duplicates The host serves the real file Redirect /index.html paths to the folder URL
Soft 404 A rewrite serves the error page with status 200 Let the host serve 404.html; no rewrites to error pages
Missing or fake <lastmod> The integration doesn’t know content dates Dates from front matter, nothing for pages without one
Duplicate or long titles Pages copied or translated from a template Length and uniqueness checks per language
Broken hreflang Links to drafts, noindex pages or missing translations One translation mapping, checked after build
Draft in the RSS feed or sitemap Each route reads content on its own One function that returns published entries
Listings without structured data Schema only added to article templates CollectionPage, ItemList, BreadcrumbList
Broken internal links after a slug change Links written by hand in Markdown Check every link against the built files
Pushed, but the live site didn’t change The deploy hook failed Check the live site after each deploy

How do you stop SEO regressions on a static site?

Turn each rule into a script that reads the built HTML and fails the build when the rule is broken. With npm, a postbuild script runs right after build; if it exits with an error, the whole build fails. A host that builds from Git doesn’t publish a failed build, so the live site keeps its previous version.

{
  "scripts": {
    "build": "astro build",
    "postbuild": "node scripts/check-seo.mjs"
  }
}

A first version can be short. This one reads every page in dist/ and checks the noindex, canonical and sitemap rules from this guide:

// scripts/check-seo.mjs
import { readdir, readFile } from 'node:fs/promises'
import { join, sep } from 'node:path'

const dist = 'dist'
const files = await readdir(dist, { recursive: true })
const sitemap = (await Promise.all(
  files.filter((f) => /sitemap-\d+\.xml$/.test(f)).map((f) => readFile(join(dist, f), 'utf8'))
)).join('')
const inSitemap = new Set([...sitemap.matchAll(/<loc>([^<]+)<\/loc>/g)].map((m) => new URL(m[1]).pathname))

const errors = []
for (const file of files.filter((f) => f.endsWith('.html') && f !== '404.html')) {
  const html = await readFile(join(dist, file), 'utf8')
  const path = '/' + file.split(sep).join('/').replace(/(^|\/)index\.html$/, '$1')
  const noindex = /<meta name="robots" content="[^"]*noindex/.test(html)
  if (noindex && html.includes('rel="canonical"')) errors.push(`${path}: noindex with a canonical`)
  if (noindex && inSitemap.has(path)) errors.push(`${path}: noindex but in the sitemap`)
  if (!noindex && !inSitemap.has(path)) errors.push(`${path}: indexable but missing from the sitemap`)
  if ((html.match(/<h1[\s>]/g) ?? []).length !== 1) errors.push(`${path}: not exactly one <h1>`)
}

if (errors.length) {
  console.error(errors.join('\n'))
  process.exit(1)
}

Grow it as you find new failure modes: titles and descriptions (length, duplicates per language), internal links that miss the slash or point to nothing, <img> without alt or dimensions, JSON-LD that doesn’t parse, hreflang that isn’t reciprocal. Write the rules down next to the checks, so the next person knows why the build failed, and never loosen a check just to get a deploy through.

Some things can’t be seen in dist/ because the host decides them: status codes, redirects, headers and the 404. Cover those after deploying:

  1. After any change to the host config, curl the redirect sources and a missing URL, and confirm the status and Location.
  2. Crawl the live site regularly. A desktop crawler such as Crawlens checks the deployed site the way a search engine sees it: redirect chains, duplicate titles, invalid JSON-LD and the rest. Comparing two crawls is the core of SEO regression testing.
  3. Watch Search Console’s page indexing report for sudden rises in duplicates, soft 404s and “Crawled – currently not indexed”.
  4. After a framework upgrade, build before and after and compare the <head> output of a few pages per template.

Static site SEO checklist

  • site set; one layout writes title, description, canonical, robots, Open Graph and hreflang.
  • Noindex pages: robots meta, no canonical, no hreflang, not in the sitemap.
  • One trailing-slash form, set in the framework and the host, used in every internal link.
  • One hostname; other hosts, index.html paths and old URLs redirect in one hop.
  • Unknown URLs return a real 404.
  • Sitemap lists only indexable URLs, with <lastmod> from content dates.
  • robots.txt declares the sitemap and isn’t used to deindex.
  • Drafts filtered in one place for pages, listings, feeds and sitemap.
  • hreflang generated from one mapping: self-reference, return links, x-default, absolute URLs.
  • JSON-LD per page type, including listings.
  • Images with dimensions and alt text; fonts self-hosted; JavaScript only where needed.
  • Post-build checks that fail the deploy; live checks after deploys and a regular crawl.

Frequently asked questions

Is a static site better for SEO than WordPress?

Not automatically. Static HTML is fast and needs no JavaScript to render, which helps crawling. But a CMS with an SEO plugin handles canonicals, sitemaps and redirects for you, while a static site only has the ones you build.

Does Astro handle SEO out of the box?

Astro renders HTML on the server or at build time, so content is in the initial response. Title, meta description, canonical, Open Graph, structured data and hreflang are tags you write in your layout. The official sitemap integration needs your site URL and your own rules for which pages to leave out.

Should static site URLs end with a trailing slash?

Either form works for Google as long as you pick one and use it everywhere. Google treats /page and /page/ as different URLs, so the other form should redirect, and internal links and the sitemap should use the preferred form.

Why does my static site's 404 page return 200?

Usually because a rewrite or catch-all route serves the error page as a normal page. Let the host serve the generated 404.html for unknown paths, then check the status code with curl after deploying.

How do I stop SEO regressions on a static site?

Run checks against the built HTML after every build: sitemap against noindex, canonicals, hreflang, internal links, titles and JSON-LD. Make the script exit with an error so the deploy fails, then crawl the live site regularly for what only the host controls.

· Founder, Crawlens

Dien builds Crawlens, a desktop crawler for technical SEO audits, and writes about the checks it runs: crawling, indexing, rendering and Search Console data.

Audit your own site with Crawlens

Crawl, run 70 checks, and see them next to Search Console and Core Web Vitals data.

Download free for Windows