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:urland 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:imageandtwitter: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’supdatedordatefrom 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-defaultnames 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>widthandheight(or an aspect ratio) and realalttext. - 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:
- After any change to the host config, curl the redirect sources and a missing URL, and confirm the status and
Location. - 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.
- Watch Search Console’s page indexing report for sudden rises in duplicates, soft 404s and “Crawled – currently not indexed”.
- After a framework upgrade, build before and after and compare the
<head>output of a few pages per template.
Static site SEO checklist
-
siteset; 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.htmlpaths 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.