SEO and sitemap
Stati adds SEO metadata to every page and can write a sitemap and a robots.txt file.
Automatic SEO injection
By default, Stati injects SEO metadata into every page during the build.
How it works
- Stati analyzes your rendered HTML before writing it to disk
- Detects any existing SEO tags in the
<head>section - Generates missing SEO metadata based on page content and configuration
- Injects the generated tags before
</head>
What gets generated
When auto-injection is enabled (default), Stati automatically generates:
- Title tag - From
seo.title, the pagetitle, or the site title - Meta description - From
seo.description, the pagedescription, orsite.description - Meta keywords - From
seo.keywords, or the pagetags - Canonical URL -
seo.canonical, or the page URL onsite.baseUrl - Author meta tag - From
seo.author, orseo.defaultAuthorin the config - Robots meta tag - Only when the page sets
seo.robotsorseo.noindex, andnoindexon the 404 page - Open Graph tags - For social media sharing (og:title, og:description, og:image, etc.), with
og:localefromsite.defaultLocaleand article tags on the pagesseo.articlesmatches - Twitter Card tags - For Twitter sharing, with
twitter:siteandtwitter:creatorfrom the handles in the config - Structured Data - JSON-LD schema when configured in front matter
Disabling auto-injection
To disable automatic SEO injection globally:
// stati.config.ts (excerpt)
import { defineConfig } from '@stati/core';
export default defineConfig({
// site: { … },
seo: {
autoInject: false, // Disable automatic SEO injection
},
});
Manual SEO generation
For complete control, you can generate SEO tags in your templates with Stati’s own stati.generateSEO(). Auto-injection still runs and adds only the tags your template does not write; set seo.autoInject: false to stop it.
Basic usage
Generate all SEO tags:
<head>
<%~ stati.generateSEO() %>
<!-- Your custom tags here -->
</head>
Selective generation
Generate only specific SEO tags using tag type strings:
<head>
<%~ stati.generateSEO(['title', 'description', 'canonical']) %>
<!-- Add custom Open Graph tags -->
<meta property="og:custom" content="value">
</head>
Available tag types
In templates, pass the strings. The SEOTagType enum is for TypeScript code that calls the SEO functions directly; import it from @stati/core/types.
'title'orSEOTagType.Title- Title tag'description'orSEOTagType.Description- Meta description'keywords'orSEOTagType.Keywords- Meta keywords'author'orSEOTagType.Author- Author meta tag'robots'orSEOTagType.Robots- Robots meta tag'canonical'orSEOTagType.Canonical- Canonical link'opengraph'orSEOTagType.OpenGraph- All Open Graph tags'twitter'orSEOTagType.Twitter- All Twitter Card tags'structuredData'orSEOTagType.StructuredData- JSON-LD structured data
SEO configuration options
Configure SEO behavior in your stati.config.ts:
// stati.config.ts
import { defineConfig } from '@stati/core';
export default defineConfig({
// site: { … },
seo: {
// Enable/disable automatic SEO injection (default: true)
autoInject: true,
// Default author for all pages
defaultAuthor: {
name: 'John Doe',
url: 'https://johndoe.com', // article:author on article pages
twitter: '@johndoe', // twitter:creator; the @ is optional
},
// The site's own handle, printed as twitter:site; the @ is optional
twitter: {
site: '@example',
},
// Pages that are articles: og:type article, plus article:* tags from the page
articles: {
include: ['/blog/*'],
exclude: [],
},
// Enable debug logging (default: false)
debug: false,
},
});
Site-wide defaults
A few Open Graph, Twitter and robots values are the same on every page, or follow from the page itself. Stati fills them in from the config and the page, so no page has to repeat them. Front matter still wins, value by value.
| Tag | From |
|---|---|
og:locale |
site.defaultLocale, converted to Open Graph form |
twitter:site |
seo.twitter.site |
twitter:creator |
The twitter handle of the page’s own seo.author, then of seo.defaultAuthor |
og:type |
article on the pages seo.articles matches, website elsewhere |
article:published_time |
The page’s publish date (publishedAt, published, date or createdAt), on article pages |
article:modified_time |
Front matter updated, an ISO 8601 date such as 2026-02-01 (a time without a zone is UTC), on article pages |
article:tag |
One per front matter tags entry, on article pages |
article:author |
The url of the page’s own seo.author, then of seo.defaultAuthor, on article pages |
robots |
noindex (seo.noindex: true) on the 404 page, unless it sets seo.noindex, or a seo.robots value that says whether to index it (index, noindex, all, none, or index: in the object form) |
Locale
site.defaultLocale is a BCP 47 tag such as en-US, the form <html lang> needs. Open Graph writes locales as language_TERRITORY, so Stati converts it: en-US becomes en_US, pt-br becomes pt_BR, and zh-Hant-TW becomes zh_TW (the script is dropped). A tag without a region, such as en, has no Open Graph form: og:locale is left out, and Open Graph assumes en_US. With seo.debug on, Stati warns about it. A page’s seo.openGraph.locale is printed as written.
Twitter handles
twitter:creator takes an @username, so it comes only from a handle, never from an author’s name: without a handle, no twitter:creator is printed. Write handles with or without @; Stati prints them with one. A page that names its own seo.author never gets the default author’s handle or URL:
---
title: Guest post
seo:
author:
name: Grace Hopper
url: https://grace.example.com
twitter: '@grace'
---
A seo.author that is a plain name gives the page no twitter:creator and no article:author.
Article pages
seo.articles.include and exclude are glob patterns matched against the page URL, with the same rules as bundle targeting: a pattern must match the whole URL, so /blog/* matches /blog/hello but not the /blog index page, and exclude wins over include. Generated pages (from a [param].md template or collections.generate) and every page of a paginated listing never match. Without seo.articles, no page is an article unless its front matter sets type: article.
On a matching page, Stati fills in each value the front matter leaves out. A page that sets only section still gets its dates and tags:
---
title: Grid or flexbox
publishedAt: 2026-01-10
updated: 2026-02-01
tags: [css, layout]
seo:
openGraph:
article:
section: CSS
---
A matching page whose front matter sets another type gets no article tags.
How defaults reach the page
Stati writes these values into each page’s seo front matter after the beforeAll hook and before rendering. So:
- Values a
beforeAllhook writes intoseowin over the defaults. - A
beforeRenderhook can change what a default comes from, such asseo.author,tagsor the URL: Stati works the defaults out again after it runs. Values the hook sets itself are kept. - Templates read the same values the head prints, such as
stati.page.seo.openGraph.type. - Changing
site.defaultLocale, a handle orseo.articlesrebuilds the cached pages it changes, like a front matter edit.
To print these tags from the config, set them here rather than in a layout: one og: or twitter: tag in the layout’s <head> turns off Stati’s whole Open Graph or Twitter group for that page (see tag type groups).
Front matter SEO fields
Customize SEO metadata for individual pages using front matter:
Open Graph configuration
With images.og, every page that sets no image gets a generated card, and its og:image, twitter:image and image size tags are added for you. Set image: false under openGraph to give a page no image at all.
---
title: My Blog Post
seo:
openGraph:
title: Custom OG Title
description: Custom OG description
type: article
image:
url: https://example.com/image.jpg
alt: Image description
width: 1200
height: 630
siteName: My Site
locale: en_US
article:
publishedTime: '2025-01-15T10:00:00Z'
modifiedTime: '2025-01-20T15:30:00Z'
author: Jane Doe
section: Technology
tags: [web, development, seo]
---
Quote dates. YAML turns an unquoted date or timestamp into a date object. An unquoted
publishedTimeormodifiedTimeis printed in JavaScript’s long date format (Wed Jan 15 2025 11:00:00 GMT+0100 ...), not ISO 8601, and an unquoted date insidestructuredDatais written as{}.
Article tags (article:published_time, article:tag and so on) are only written when type is article. On the pages seo.articles matches, the type and the article values the front matter leaves out are filled in from the page. locale is printed as written; without it, og:locale comes from site.defaultLocale. Image URLs that start with / are made absolute with site.baseUrl.
Twitter card configuration
---
title: My Blog Post
seo:
twitter:
card: summary_large_image
site: '@mysite'
creator: '@janedoe'
title: Custom Twitter title
description: Custom Twitter description
image: https://example.com/twitter-image.jpg
imageAlt: Twitter card image description
---
site and creator are printed as written. Without them, they come from the handles in the config.
Structured data (Schema.org)
---
title: Product Page
seo:
structuredData:
'@context': https://schema.org
'@type': Product
name: Amazing Product
description: The best product ever
image: https://example.com/product.jpg
brand:
'@type': Brand
name: My Brand
offers:
'@type': Offer
price: 29.99
priceCurrency: USD
---
Stati writes the object as JSON-LD exactly as you wrote it. &, quotes and apostrophes are not turned into HTML entities, because the text inside a <script> element is not HTML. Every < in a key or a value is written as \u003c, so a value such as </script> stays inside the JSON and parses back unchanged.
Robots configuration
---
title: My Page
seo:
robots:
index: true # Allow indexing (default: true)
follow: true # Allow following links (default: true)
archive: true # Allow archiving
snippet: true # Allow snippets in search results
imageindex: true # Allow indexing images
maxSnippet: 160 # Maximum snippet length
maxImagePreview: large # Image preview size: none, standard, large
maxVideoPreview: -1 # Video preview duration (-1 = no limit)
---
A page that sets index: false here, seo.noindex: true, or a seo.robots string with a noindex or none directive is left out of the sitemap.
Sitemap configuration
Stati can automatically generate XML sitemaps for your site.
Production Only: Sitemaps are only generated during production builds (
stati build). They are skipped in development mode to improve build performance.
Enable sitemap generation
// stati.config.ts
import { defineConfig } from '@stati/core';
export default defineConfig({
site: {
title: 'My Site',
baseUrl: 'https://example.com', // Used for the absolute URLs in the sitemap
},
sitemap: {
enabled: true,
},
});
Advanced sitemap options
// stati.config.ts
import { defineConfig } from '@stati/core';
export default defineConfig({
site: {
title: 'My Site',
baseUrl: 'https://example.com', // Used for absolute URLs
},
sitemap: {
enabled: true,
// Default priority for all pages (0.0 to 1.0; 0.5 if not set)
defaultPriority: 0.5,
// Default change frequency (no <changefreq> is written if not set)
defaultChangeFreq: 'monthly',
// Exclude pages whose URL matches (see "Pattern matching" below)
excludePatterns: ['/draft', '/admin'],
// Include only pages whose URL matches (if specified)
includePatterns: ['/blog', '/docs'],
// Filter pages to include in sitemap
filter: (page) => {
// Exclude draft pages
return !page.frontMatter.draft;
},
// Transform URLs before adding to sitemap
transformUrl: (url, page, config) => {
// Add trailing slash
return url.endsWith('/') ? url : `${url}/`;
},
// Transform individual sitemap entries
transformEntry: (entry, page) => {
// Customize entry or return null to exclude
if (page.frontMatter.exclude) {
return null; // Exclude this entry
}
return {
...entry,
priority: page.frontMatter.important ? 1.0 : entry.priority,
};
},
// Priority rules based on URL patterns (first match wins)
priorityRules: [
{ pattern: '/', priority: 1.0 },
{ pattern: '/blog/**', priority: 0.8 },
{ pattern: '/docs/**', priority: 0.9 },
],
},
});
Validation. defaultPriority must be a number from 0.0 to 1.0, and defaultChangeFreq one of the change frequency values. Any other value stops the build with an Invalid sitemap configuration error.
Pattern matching. excludePatterns, includePatterns and priorityRules[].pattern are matched against page URLs such as /blog/first-post (/ for the home page):
- A pattern with
*or?is a glob that must match the whole URL:/blog/**matches/blog/first-postbut not the/blogindex page. - A pattern without wildcards matches that URL and everything below it:
/blogmatches/blogand/blog/first-post, but not/blog-archive. The pattern/matches only the home page.
Pages with draft: true are never in the sitemap (they are not built), so filter: (page) => !page.frontMatter.draft is only needed for builds with --include-drafts.
Two more kinds of page are left out without a pattern: the 404 page, and pages whose robots meta tag says noindex (seo.noindex: true, seo.robots: { index: false }, or a seo.robots string with a noindex or none directive). Search engines report a sitemap URL marked noindex as an error. A page that sets sitemap: { exclude: false } in front matter stays in despite both (the 404 page also needs seo.noindex: false, or it is listed as noindex); excludePatterns, includePatterns and filter still apply to it.
Pages created from a [param].md template and the later pages of a paginated listing (/blog/page/2) are in the sitemap like any other page. Leave them out with a pattern such as excludePatterns: ['/blog/page/**'], sitemap: { exclude: true } in the template’s front matter, or a filter that checks page.generated and page.pagination.
Output. lastmod comes from the page’s sitemap.lastmod, then updated front matter, then its publish date (the first valid of publishedAt, published, date and createdAt). A date is written as 2024-03-04, and a value with a time as the same moment in UTC: 2024-03-04T23:30:00-05:00 becomes 2024-03-05T04:30:00Z. URLs are percent-encoded, as the sitemap protocol requires, so a page at /blog/My Post or /café is listed as /blog/My%20Post or /caf%C3%A9, and an internationalized domain in site.baseUrl in its xn-- form; escapes a URL already has are kept. Priorities are written with one decimal place, so 0.85 becomes 0.8. Above 50,000 URLs the sitemap is split into sitemap-1.xml, sitemap-2.xml, … with sitemap.xml as the index; this happens automatically (the generateIndex option is not used).
Per-page sitemap configuration
Control sitemap behavior for individual pages using front matter:
---
title: My Page
sitemap:
exclude: false # true leaves the page out; false keeps a noindex or 404 page in
priority: 0.8 # Priority (0.0 to 1.0), overrides priorityRules
changefreq: weekly # Change frequency
lastmod: '2025-01-20' # Last modification date
---
The sitemap reads only this sitemap block; seo.priority and seo.changeFreq are not used for it. On a page that is neither the 404 page nor marked noindex, exclude: false is the same as leaving exclude out.
Change frequency values
always, hourly, daily, weekly, monthly, yearly and never. Front matter changefreq is read in any letter case (Weekly is weekly). Any other changefreq value is ignored, and the page falls back to defaultChangeFreq.
Google News sitemap
News publishers can have Stati write a Google News sitemap (the news: namespace) as a separate file, so no build hook is needed. Set sitemap.news next to enabled: true:
// stati.config.ts
import { defineConfig } from '@stati/core';
export default defineConfig({
site: {
title: 'Stati News',
baseUrl: 'https://example.com',
defaultLocale: 'en-US',
},
sitemap: {
enabled: true,
news: {
// URL globs of the articles, like seo.articles.include (required)
include: ['/news/*/*'],
// Name of the publication (default: site.title)
publicationName: 'Stati News',
// Language of the publication (default: from site.defaultLocale, or 'en')
language: 'en',
// Articles published longer ago than this are left out (default: 2)
maxAgeDays: 2,
// File name in the output folder (default: 'news-sitemap.xml')
filename: 'news-sitemap.xml',
},
},
robots: {
enabled: true,
sitemap: true, // lists sitemap.xml and news-sitemap.xml
},
});
Without sitemap.news nothing changes: no file is written. With it, production builds (stati build) write the file next to sitemap.xml, with one <url> per article:
<url>
<loc>https://example.com/news/world/first-article</loc>
<news:news>
<news:publication>
<news:name>Stati News</news:name>
<news:language>en</news:language>
</news:publication>
<news:publication_date>2026-10-25T07:00:00.000Z</news:publication_date>
<news:title>First article</news:title>
</news:news>
</url>
- Which pages. Pages whose URL matches
include(the same globs asseo.articles.include:*stays within one URL segment,**crosses segments) and that were published withinmaxAgeDays. The publication date is the page’s publish date (the first valid ofpublishedAt,published,dateandcreatedAtfront matter) and is written as ISO 8601 in UTC. The title is the page’stitlefront matter. Stati warns about a matching page that has no valid date or no title and leaves it out, so chooseincludepatterns that select articles only (/news/*/*skips the section pages at/news/world). A future date is listed as it is. - Left out. Drafts, pages created from a
[param].mdtemplate, later pages of a paginated listing, the 404 page, pages markednoindex, and pages withsitemap: { exclude: true }. A page that setssitemap: { exclude: false }stays in despitenoindex. The sitemap’sexcludePatterns,includePatterns,filter,transformUrlandtransformEntrydo not apply to the news sitemap;includeselects its pages. - Order and size. Newest first, at most 1000 URLs (the oldest are dropped, with a warning). When no article is recent enough, the file is still written as a valid
urlsetwith no<url>elements. - URLs. Absolute, from
site.baseUrlincluding its base path, and percent-encoded like those insitemap.xml; titles and URLs are XML-escaped. - robots.txt. With
robots.sitemap: true,robots.txtlists the news sitemap aftersitemap.xml, so nocustomLinesentry is needed (an existingSitemap:line for it is not repeated). An explicitrobots.sitemapURL lists only that URL. The news sitemap is not written, nor listed, whensitemap.enabledis off. - Validation.
includemust be an array of strings,languagean ISO 639 code such asen(orzh-cn,zh-tw) rather than a locale likeen-US,maxAgeDaysa number above 0, andfilenamean.xmlfile name of letters, digits,.,_and-(no folder) that is notsitemap.xmlorsitemap-<n>.xmlin any case; anything else fails the build with a message naming the option.
Freshness. Google News reads the articles of the last two days, and Stati decides which articles are recent when it builds. A site that is built once and served for weeks keeps the list of that day. Rebuild whenever you publish, or on a schedule (for example a nightly or hourly CI job), so the file follows the clock.
robots.txt configuration
Generate a robots.txt file to control search engine crawling.
Production Only: The robots.txt file is only generated during production builds (
stati build). It is skipped in development mode to improve build performance.
Enable robots.txt
// stati.config.ts
import { defineConfig } from '@stati/core';
export default defineConfig({
site: { title: 'My Site', baseUrl: 'https://example.com' },
robots: {
enabled: true,
},
});
With no rules configured, this writes User-agent: * and Allow: /. The Sitemap: line is only added when you set robots.sitemap (see below).
Crawlers read robots.txt only at the root of a host. For a site served from a subfolder, see robots.txt.
Advanced robots.txt options
// stati.config.ts
import { defineConfig } from '@stati/core';
export default defineConfig({
// site: { … },
robots: {
enabled: true,
// User agent specific rules
userAgents: [
{
userAgent: 'Googlebot',
allow: ['/public/'],
disallow: ['/admin/', '/private/'],
},
{
userAgent: 'Bingbot',
disallow: ['/admin/'],
},
],
// Global disallow rules (applies to all user agents)
disallow: [
'/admin/',
'/private/',
'/api/',
],
// Global allow rules (useful with disallow wildcards)
allow: [
'/api/public/',
],
// Crawl delay in seconds, written in the "User-agent: *" group (be careful with this)
crawlDelay: undefined,
// Sitemap reference: a URL, or true for <baseUrl>/sitemap.xml and, with sitemap.news,
// the Google News sitemap (not added when unset)
sitemap: 'https://example.com/sitemap.xml',
// Custom lines to add to robots.txt
customLines: [
'User-agent: AnotherBot',
'Disallow: /restricted/',
],
},
});
Example robots.txt output
With the above configuration, Stati generates:
User-agent: Googlebot
Allow: /public/
Disallow: /admin/
Disallow: /private/
User-agent: Bingbot
Disallow: /admin/
User-agent: *
Allow: /api/public/
Disallow: /admin/
Disallow: /private/
Disallow: /api/
Sitemap: https://example.com/sitemap.xml
User-agent: AnotherBot
Disallow: /restricted/
Paths without a leading / get one. An empty path writes the line with no value: disallow: [''] writes Disallow:, which blocks nothing, while Disallow: / would block the whole site. crawlDelay is written only when it is greater than 0. Global options that write no line (crawlDelay: 0, or empty allow and disallow lists) add no User-agent: * group, so without other rules Stati writes the default Allow: /.
SEO tag types
Tag type groups
Some tag types are grouped, meaning if you manually add any tag from a group, Stati skips auto-generating all tags in that group:
- Open Graph Group: If any
og:*tag exists, all Open Graph tags are skipped - Twitter Group: If any
twitter:*tag exists, all Twitter Card tags are skipped
This prevents duplicate or conflicting tags.
Troubleshooting
Why aren’t my SEO tags being injected?
Check these common issues:
- Auto-injection disabled: Verify
seo.autoInjectistrue(default) - Tags already exist: Stati skips tags that already exist in your HTML
- Invalid front matter: Check for YAML syntax errors
- Missing
</head>: Auto-injection requires a closing</head>tag
How do I debug SEO generation?
Enable debug mode to see detailed logs:
// stati.config.ts
import { defineConfig } from '@stati/core';
export default defineConfig({
// site: { … },
seo: {
debug: true, // Enable detailed SEO logging
},
});
Why are some tags missing?
Common reasons:
- Group behavior: Adding any Open Graph tag manually skips all OG tags
- Missing data: No source data available (e.g., no page description, so no description tags)
- No
</head>: Tags are injected before</head>; a layout without it gets none
How do I override specific tags?
Use hybrid mode - keep auto-injection enabled and add manual tags for specific fields:
<head>
<!-- Manual title overrides auto-generated title -->
<title>Custom Title</title>
<!-- All other tags are auto-generated -->
</head>
Front matter validation
When seo.autoInject is on (the default), Stati checks each page’s seo front matter during the build and logs what it finds; none of these stop the build, and the tags are still generated with the values you gave:
- Errors, such as a
seo.canonicalthat is not an absolutehttporhttpsURL, or aseo.priorityoutside 0.0 to 1.0. - Warnings, such as a
seo.titleorseo.descriptionof unusual length.
The full list is in SEOValidationResult. Errors are always logged; warnings are only logged when seo.debug is true. With autoInject off, nothing is logged: stati.generateSEO() does not report these checks.
Next steps
- SEO Usage Scenarios - Learn different approaches to using SEO in your project
- SEO API - Detailed API documentation for SEO functions and types