vite-plugin-geo
English | 简体中文
Post-build discovery file generator and static verifier for Vite, Vite+, and Astro sites. Generates sitemap.xml, robots.txt, RSS 2.0 feed.xml, llms.txt v2, clean per-page Markdown mirrors, and optional humans.txt and sku.md manifests from a single validated build plan.
Scope note: Generated files are machine-readable discovery and crawl hints. They do not guarantee crawling, indexing, ranking, AI citation, or traffic outcomes from any search engine or AI system.
Table of contents
- Features
- Requirements
- Installation
- Quick start
- Generated files
- Configuration
- Astro sitemap compatibility
- CLI and CI verification
- Build diagnostics
- Common recipes
- Specification contract
- Contributing
- Changelog
- License
Features
- Sitemap 0.9 generation and splitting. Builds URL sets from emitted HTML with configurable
trailingSlashnormalization, splits files automatically above 50,000 URLs orsitemapMaxBytes(up to 50 MiB), and coexists with@astrojs/sitemap. - RFC 9309
robots.txthandling. Preserves hand-writtenrobots.txtbyte-for-byte by default, validates custom directives against control characters and the 500 KiB limit, and writes only to the site root. - RSS 2.0 feed discovery. Emits
feed.xml(or locale-scoped feeds withfeedByLocale) with an Atomselflink, include/exclude filters, item caps, language override, and idempotent<link rel="alternate" type="application/rss+xml">injection. llms.txtv2 and Markdown mirrors. Injectsrel="describedby"andrel="alternate" type="text/markdown"links, scopes mirrors withllmsMdMirrorInclude/llmsMdMirrorExclude, and extracts clean<main>or single-<article>prose (with GFM tables,<details>/<summary>,data-geo-ignore,markdownStripSelectors, and single-H1 enforcement) into.mdmirrors without navigation or form noise.- Multilingual
hreflangsupport. Populates Sitemapxhtml:linkalternates from global route templates or per-page HTML<link rel="alternate" hreflang="...">tags (hreflangFromHtml). - Optional
humans.txtandsku.md(1.0.0-beta). Emits verified team metadata and root-level pure Markdown merchant catalogs without fabricating missing fields. - Static build diagnostics and read-only
verify. Prints deterministic page and link diagnostics during builds (audit), and verifies finaldist/outputs after all plugins finish (vite-plugin-geo verify) with JSON (schemaVersion: "1.0") and SARIF 2.1.0 reports. - Shared pipeline across Vite, Vite+, Astro, and CLI. Runs identical option validation, conflict resolution, planning, and ownership checks across Vite/Vite+ builds, Astro integrations, and the CLI.
Requirements
- Node.js:
^20.19.0 || >=22.12.0(vite-plusitself requires^22.18.0 || ^24.11.0 || >=26.0.0) - Vite:
^7.0.0 || ^8.0.0(optional peer dependency; pure CLI or Astro-only projects do not require a direct Vite install) - Vite+:
vite-plus^1.x(bundles Vite 8 and Rolldown via@voidzero-dev/vite-plus-core) - Astro:
^7.0.0(optional peer dependency; pure Vite projects do not need Astro installed)
Installation
npm install -D vite-plugin-geo
pnpm add -D vite-plugin-geo
yarn add -D vite-plugin-geo
bun add -d vite-plugin-geo
In Vite+ workspaces:
vp add -D vite-plugin-geo
Quick start
Vite
Add the default plugin export to vite.config.js:
// vite.config.js
import { defineConfig } from 'vite';
import geo from 'vite-plugin-geo';
export default defineConfig({
plugins: [
geo({
domain: 'https://example.com',
}),
],
});
domain must be an HTTP(S) origin containing only scheme, host, and optional port (for example, https://example.com). Do not include credentials, paths, query strings, or fragments. Express subpath deployments with routeBasePath.
You can also store domain in your project package.json. When both exist, geo({ domain }) wins. If package.json has no domain, an absolute homepage URL (for example, "homepage": "https://example.com") is used instead. It must follow the same origin-only rule. Relative values such as "." are ignored. When none of these exist, the build stops instead of emitting broken public URLs.
Named exports are also available:
import geo, { createGeoGeneratorPlugin, verifyGeoOutput } from 'vite-plugin-geo';
Vite build notes:
distDirdefaults to Vite's resolvedbuild.outDir, androuteBasePathdefaults to Vite'sbase.- The plugin sets
apply: 'build'and runs ingenerateBundle(enforce: 'post') viathis.emitFile, sobuild.write: falseis respected and plugin outputs take precedence over duplicate files inpublicDirwhile still respectingfileConflict,sitemapConflict, andgenerateRobotsfor user-owned files. - SSR, library, and non-HTML server environments do not emit static HTML and skip GEO generation; in multi-environment builds, only browser/client HTML output emits discovery files.
Vite+
Vite+ (vite-plus) bundles Vite 8 and Rolldown through @voidzero-dev/vite-plus-core, so vite-plugin-geo works directly in vite.config.ts without a separate wrapper entry point:
// vite.config.ts
import { defineConfig, lazyPlugins } from 'vite-plus';
import geo from 'vite-plugin-geo';
export default defineConfig({
plugins: lazyPlugins(() => [
geo({
domain: 'https://example.com',
}),
]),
});
Vite+ notes:
- Wrap plugin registration with
lazyPlugins(() => [...])from'vite-plus'sovp check,vp lint, andvp fmtskip plugin factory execution during metadata resolution (VP_RESOLVING_CONFIG_METADATA=1). - Use
vp buildfor web application builds (which executes the Vite + Rolldown pipeline).vp packrunstsdownfor libraries and standalone binaries and does not produce HTML pages. - Because
vite-plusmapsviteto@voidzero-dev/vite-plus-core@1.xrather thanvite@7/8, keep the standard Vite+overrides(npm/pnpm) andpnpm.peerDependencyRulesgenerated byvp createorvp migrate. - When running
generateHumans: truein a Vite+ project whosepackage.jsonlistsvite-plus(without a directviteentry),humans.txtrecordsvite-plusunderComponents:.
Astro
Astro emits final HTML after its internal Vite build completes. Do not register vite-plugin-geo inside vite.plugins in Astro projects. Choose one of the two supported workflows below (do not combine both).
Important: Astro
integrationsmust import from'vite-plugin-geo/astro'(import geo from 'vite-plugin-geo/astro'). Passing the default'vite-plugin-geo'Vite plugin export intointegrationsthrows an explicit configuration error duringastro:config:setup.
Option 1: Native Astro integration (recommended)
// astro.config.mjs
import { defineConfig } from 'astro/config';
import geo from 'vite-plugin-geo/astro';
export default defineConfig({
site: 'https://example.com',
integrations: [geo()],
});
Domain resolution order in Astro is geo({ domain }), then Astro site, then package.json.domain, then an absolute package.json.homepage.
Astro integration notes:
- When
prettyUrlsis not explicitly configured and Astrobuild.formatis'file',vite-plugin-geo/astrodisablesprettyUrlsso public links match.htmloutputs. - When
trailingSlashis not explicitly configured,vite-plugin-geo/astroautomatically aligns with Astro'sconfig.trailingSlash('always' -> 'always','never' -> 'never','ignore' -> 'preserve'). Markdown mirrors always keep/about.md(never/about/.md). - Redirect entries reported by Astro (
route.type === 'redirect') are excluded fromsitemap.xml,llms.txt,feed.xml, Markdown mirrors, and static audits.
Option 2: Post-build CLI
{
"domain": "https://example.com",
"scripts": {
"build": "astro build && vite-plugin-geo generate"
}
}
The CLI scans dist/ by default and does not parse astro.config.*. If your origin is set only in Astro site, pass --domain https://example.com (and --dist-dir <path> for custom output directories such as Astro's configured outDir).
Default build output:
dist/
├── sitemap.xml
├── robots.txt
├── feed.xml
├── llms.txt
├── index.md
└── ...other-pages.md
Generated files
| File | Default | Behavior |
|---|---|---|
sitemap.xml |
Enabled (auto) | Lists public page URLs respecting trailingSlash; splits and writes sitemap_index.xml above 50,000 URLs or sitemapMaxBytes. Skips automatically when an external Sitemap is detected. |
sitemap_index.xml |
Conditional | Emitted automatically when Sitemap sharding triggers and sitemapIndex: true. |
robots.txt |
Auto | Preserves any hand-written robots.txt; otherwise generates at the root scope (/) and skips non-root routeBasePath scopes. Always targets /robots.txt. |
feed.xml |
Enabled | Emits RSS 2.0 with Atom self link and injects HTML discovery <link> tags. Can be filtered, capped, language-overridden, or split per locale (feedByLocale). |
llms.txt |
Enabled | Emits the single-scope llms.txt v2 index for the configured routeBasePath. Links to .md mirrors when generated, or falls back to HTML pageUrl when a mirror is excluded. |
*.md |
Enabled | Per-page Markdown mirrors derived from public pagePath, containing # <title>, > <description>, and cleaned <main> or <article> content. Always uses /about.md (never /about/.md). |
humans.txt |
Disabled | Emits verified author, license, and runtime details derived from explicit config and package.json. |
sku.md |
Disabled | Emits a root-level SKU.md 1.0.0-beta catalog manifest when skuMd is configured. |
Directory format & mirror naming: Under build.format: 'directory' (or */index.html directories) with prettyUrls: true, directory index pages map directly to llms.txt public-path mirror names: about/index.html -> about.md and zh/index.html -> zh.md (while index.html -> index.md). Even when trailingSlash: 'always' is active on HTML page URLs (/about/, /zh/), .md mirrors keep /about.md and /zh.md without a trailing slash.
Markdown mirror extraction: Content extraction prefers <main>, then a single <article>, falling back to <body> without site chrome. It strips [hidden], [aria-hidden="true"], [data-geo-ignore], <form>, <input>, <select>, <textarea>, <button>, <nav>, [role="navigation"], breadcrumb navigation, and any custom markdownStripSelectors. It also emits GFM pipe tables (with or without <thead>), normalizes multi-element <a> cards into clean [Title](href) links with body text and proper adjacent inline spacing, formats <details>/<summary> blocks cleanly, and enforces a single top-level # H1 (deduplicating a matching leading <h1> and downgrading remaining body # headings outside fenced code blocks to ##).
RSS feed behavior note: With the default lastmodStrategy: 'none', RSS <item> entries omit <pubDate> and are sorted deterministically by URL. For non-blog or utility/tool sites, either set generateFeed: false or restrict feed items to article/changelog paths with feedIncludePatterns (and enable lastmodStrategy: 'git' or 'file-mtime' when chronological <pubDate> ordering is needed).
Ownership and conflict handling: Files written by this plugin carry a format-specific Generated by vite-plugin-geo marker and are regenerated on subsequent builds. Removing the marker marks a file as user-owned. When a user-owned llms.txt, feed.xml, humans.txt, sku.md, or *.md mirror already exists, fileConflict defaults to 'preserve' (warns and keeps the user file while generating remaining outputs; preserving a hand-written llms.txt alongside generated .md mirrors emits a build warning so you know to keep manual llms.txt links in sync). Set fileConflict: 'error' to fail before writing, or 'overwrite' to replace user files. sitemap.xml and robots.txt use sitemapConflict and generateRobots.
Configuration
| Option | Type | Default | Description |
|---|---|---|---|
domain |
string |
package.json.domain, then package.json.homepage |
Public HTTP(S) origin without credentials, path, query, or hash. |
distDir |
string |
Vite build.outDir |
Build output directory (not applicable to vite-plugin-geo/astro). |
routeBasePath |
string |
Vite or Astro base |
Single public path scope (for example, '/docs/'). Rejects full URLs. |
prettyUrls |
boolean |
true |
Strip .html extensions from public page URLs. |
trailingSlash |
'never' | 'always' | 'preserve' |
'never' (Astro: syncs config.trailingSlash) |
Trailing-slash policy for root and extensionless public URLs; files with extensions (.md, .html, .xml, .txt) never receive a trailing slash. 'preserve' honors each page's <link rel="canonical"> trailing slash when declared. |
lastmodStrategy |
'none' | 'file-mtime' | 'build' | 'git' |
'none' |
Timestamp source for Sitemap <lastmod> and RSS <pubDate>. |
excludePatterns |
string[] |
['404.html', '500.html'] |
Glob patterns excluded from discovery outputs and link injection. |
hreflang |
Record<string, string> |
undefined |
Global language alternate URL templates using {path}. |
hreflangFromHtml |
boolean |
false |
Read per-page <link rel="alternate" hreflang> tags for Sitemap xhtml:link; falls back to hreflang on pages without HTML declarations. |
generateSitemap |
boolean |
Auto | Disabled automatically when an external Sitemap is present. |
sitemapConflict |
'preserve' | 'error' | 'overwrite' |
Auto | Policy when an external Sitemap is found; preserves with a warning by default. |
sitemapUrl |
string |
Auto | Explicit Sitemap URL or path referenced in robots.txt and llms.txt. |
fileConflict |
'preserve' | 'error' | 'overwrite' |
'preserve' |
Conflict policy for user-owned llms.txt, feed.xml, humans.txt, sku.md, and *.md mirrors. |
routeConflict |
'error' | 'first' | 'last' |
'error' |
Fail or deterministically pick one file when multiple HTML files map to the same public route. |
llmsMdMirror |
boolean |
true |
Generate Markdown mirrors for pages lacking a valid Markdown alternate. |
llmsMdMirrorStyle |
'append' | 'replace' |
'append' |
Mirror filename derivation. Under prettyUrls: false, append produces about.html.md and replace produces about.md. |
llmsMdMirrorInclude |
string[] |
undefined |
Glob patterns selecting which pages emit .md mirrors and Markdown alternate links. Unmatched pages fall back to HTML URLs in llms.txt. |
llmsMdMirrorExclude |
string[] |
undefined |
Glob patterns excluding pages from .md mirror generation (excluded pages fall back to HTML URLs in llms.txt). |
markdownStripSelectors |
string[] |
[] |
CSS selectors stripped from extracted HTML before Markdown mirror conversion (in addition to data-geo-ignore, forms, buttons, hidden elements, and nav). |
llmsClassify |
(page: LlmsPageInfo) => string | null | undefined |
Auto | Custom section classifier for llms.txt. |
llmsSections |
Record<string, string | string[]> |
Auto | Path-prefix to section mapping for llms.txt. |
generateRobots |
boolean |
Auto | Preserves hand-written robots.txt; otherwise generates on / scope only. Explicit true throws if a hand-written file exists. |
robotsDirectives |
string[] |
[] |
Custom robots.txt directives validated against RFC 9309 constraints. |
generateFeed |
boolean |
true |
Enable RSS 2.0 feed.xml generation and HTML discovery link injection. |
feedIncludePatterns |
string[] |
undefined |
Glob patterns limiting which pages are included in RSS feeds. |
feedExcludePatterns |
string[] |
undefined |
Glob patterns excluding pages from RSS feeds. |
feedMaxItems |
number |
undefined |
Maximum number of <item> entries emitted per RSS feed (positive integer). |
feedLanguage |
string |
Home <html lang> or 'en' |
Explicit BCP 47 <language> tag for feed.xml (and fallback when feedByLocale: true). |
feedByLocale |
boolean |
false |
Generate separate locale-scoped RSS feeds grouped by page locale instead of a single mixed-language feed.xml. |
generateHumans |
boolean |
false |
Enable humans.txt generation. |
skuMd |
SkuMdOptions |
undefined |
Root /sku.md (1.0.0-beta) merchant manifest configuration. |
audit |
boolean |
true |
Run static HTML and discovery diagnostics during the build. |
auditFailOn |
'warning' | 'advice' |
Disabled | Fail the build before writing files when diagnostics reach this severity. |
debug |
boolean |
false |
Print resolved URLs, excluded pages, Sitemap decisions, and mirror summaries. |
Advanced options
| Option | Type | Default | Description |
|---|---|---|---|
stripPathPrefixes |
string[] |
['src/pages/'] |
Source path prefixes stripped when computing public URLs. |
sourceHtmlDir |
string |
'src/pages' |
Source HTML directory used by file-mtime and git timestamp lookups. |
packageJsonPath |
string | false |
'./package.json' |
Path to package.json, or false to disable reading package metadata. |
sitemapIndex |
boolean |
true |
Allow automatic Sitemap sharding and sitemap_index.xml generation. |
sitemapMaxBytes |
number |
52428800 |
Maximum uncompressed bytes per Sitemap shard (up to 50 MiB). |
lastmodIgnore |
string[] |
[] |
Glob patterns skipped during lastmod resolution. |
lastmodResolver |
(page: GeoPageModel) => Date | string | null | undefined |
undefined |
Plugin API only. Return a Date or valid W3C Datetime string; null omits lastmod, undefined falls back to lastmodStrategy, and invalid values throw during planning. |
skuMd.merchantName |
string |
Home page <title> |
Merchant heading; fails the build if neither configured nor derivable. |
skuMd.summary |
string |
Home page description | Merchant summary; fails the build if neither configured nor derivable. |
skuMd.catalog |
Array<{ label: string; url: string }> |
Required | One or more same-origin HTTPS catalog entry links. |
Removed legacy keys (llmsFull, llmsCtx, llmsCtxFull, blockGoogleExtended, stability*, and legacy skuMd fields catalogUrl, contentLanguage, market) throw explicit configuration errors rather than being silently ignored.
Astro sitemap compatibility
If your Astro project already uses @astrojs/sitemap, place sitemap() before geo() so @astrojs/sitemap writes its sitemap files before vite-plugin-geo/astro inspects dist/ during astro:build:done (if @astrojs/sitemap is registered after geo(), astro:config:done emits a warning):
import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';
import geo from 'vite-plugin-geo/astro';
export default defineConfig({
site: 'https://example.com',
integrations: [sitemap(), geo()],
});
During astro:build:done, vite-plugin-geo inspects emitted Sitemap artifacts on disk:
- Preserves the external Sitemap by default and logs its filename, source,
<loc>count, and up to 3 sample URLs. - Continues generating
llms.txt,robots.txt,feed.xml, and Markdown mirrors. - Points
robots.txtandllms.txtto the detected Sitemap index or file (including customfilenameBasenames).
To replace an external Sitemap intentionally, declare both generateSitemap: true and sitemapConflict: 'overwrite':
geo({
generateSitemap: true,
sitemapConflict: 'overwrite',
sitemapUrl: 'sitemap.xml',
})
CLI and CI verification
Run generation or post-build verification directly from the command line:
# Generate discovery files from dist/
npx vite-plugin-geo generate --domain https://example.com --dist-dir dist
# Use a JSON config file
npx vite-plugin-geo generate --config ./geo.config.json
# Read-only verification of final dist/ artifacts
npx vite-plugin-geo verify --dist-dir dist --domain https://example.com
npx vite-plugin-geo verify --dist-dir dist --report json > geo-report.json
npx vite-plugin-geo verify --dist-dir dist --report sarif --report-file geo.sarif
npx vite-plugin-geo verify --dist-dir dist --fail-on-verify warning
# Generate, verify immediately, and gate on audit warnings
npx vite-plugin-geo generate --verify --fail-on-audit warning
verify reads the final dist/ directory without writing files, making it immune to third-party closeBundle overwrite races. It checks Sitemap <loc> counts, home page presence, leaked build prefixes (such as /src/pages/), .html extension leaks, duplicate <loc> entries, <loc>-to-file mapping, robots.txt Sitemap: consistency, canonical alignment, llms.txt, feed.xml, and Markdown mirrors (recursing Sitemap indexes up to 5 levels).
When --report json or --report sarif writes to stdout, human-readable logs route to stderr automatically so stdout stays valid for pipes.
Vite+ projects can run the CLI via vp exec or vpx and wire read-only verification as a cached downstream vp run task:
vp build
vp exec vite-plugin-geo verify --dist-dir dist --domain https://example.com
In a Vite+ monorepo, running vite-plugin-geo from the repository root reads ./package.json unless you pass --domain or --package-json-path:
vp build apps/web
vp exec vite-plugin-geo verify --dist-dir apps/web/dist --package-json-path apps/web/package.json
If using Vite Task (run.tasks in vite.config.ts), keep GEO generation inside vp build (as a Vite plugin) and place vite-plugin-geo verify in a downstream task with dependsOn so two tasks do not overwrite the same dist/ files.
GitHub Actions SARIF workflow example:
- run: npm run build
- run: npx vite-plugin-geo verify --dist-dir dist --domain https://example.com --report sarif --report-file geo.sarif --fail-on-verify warning
- uses: github/codeql-action/upload-sarif@v3
if: always()
with:
sarif_file: geo.sarif
Full CLI flag reference
generate is the default command when no subcommand is given.
| Flag | Description |
|---|---|
--domain <url> |
Public site origin; overrides package.json.domain and homepage. |
--dist-dir <path> |
Build output directory (default: dist). |
--route-base-path <path> |
Single public URL subpath prefix. |
--source-html-dir <path> |
Source HTML directory (default: src/pages). |
--package-json-path <path> |
Path to package.json, or --package-json-path=false. |
--strip-path-prefixes <list> |
Comma-separated source path prefixes to strip. |
--exclude-patterns <list> |
Comma-separated exclusion globs. |
--trailing-slash <mode> |
never, always, or preserve (default: never). |
--lastmod-strategy <value> |
none, file-mtime, build, or git. |
--lastmod-ignore <list> |
Comma-separated globs skipped by lastmod. |
--llms-md-mirror-style <value> |
append or replace. |
--llms-md-mirror-include <list> |
Comma-separated globs selecting pages for .md mirror generation. |
--llms-md-mirror-exclude <list> |
Comma-separated globs excluding pages from .md mirror generation. |
--markdown-strip-selectors <list> |
Comma-separated CSS selectors stripped before Markdown mirror conversion. |
--robots-directives <list> |
Comma-separated custom robots.txt directives. |
--sitemap-url <path-or-url> |
Sitemap URL or path referenced by robots.txt and llms.txt. |
--sitemap-conflict <mode> |
preserve, error, or overwrite. |
--file-conflict <mode> |
preserve, error, or overwrite (default: preserve). |
--route-conflict <mode> |
error, first, or last (default: error). |
--hreflang-from-html / --no-hreflang-from-html |
Toggle per-page HTML hreflang extraction. |
--fail-on-audit <level> |
none, warning, or advice (default: none). |
--fail-on-verify <level> |
none, error, or warning (default: error). |
--report <json|sarif> |
Emit a machine-readable report (json or sarif). |
--report-file <path> |
Write the report to a file instead of stdout. |
--verify / --no-verify |
Toggle running verify immediately after generate. |
--pretty-urls / --no-pretty-urls |
Toggle .html extension stripping. |
--sitemap-index / --no-sitemap-index |
Toggle automatic Sitemap index sharding. |
--generate-sitemap / --no-generate-sitemap |
Toggle Sitemap generation. |
--generate-robots / --no-generate-robots |
Toggle robots.txt generation. |
--llms-md-mirror / --no-llms-md-mirror |
Toggle Markdown mirror generation. |
--generate-feed / --no-generate-feed |
Toggle RSS 2.0 feed.xml generation. |
--feed-include-patterns <list> |
Comma-separated globs limiting pages included in RSS feeds. |
--feed-exclude-patterns <list> |
Comma-separated globs excluding pages from RSS feeds. |
--feed-max-items <number> |
Maximum number of items emitted per RSS feed. |
--feed-language <tag> |
Explicit BCP 47 <language> tag for generated RSS feeds. |
--feed-by-locale / --no-feed-by-locale |
Toggle per-locale RSS feed generation. |
--generate-humans / --no-generate-humans |
Toggle humans.txt generation. |
--audit / --no-audit |
Toggle build diagnostics (also accepts --audit=true|false). |
--debug / --no-debug |
Toggle verbose planning summary. |
--config <path> |
Load options from a JSON file. |
Build diagnostics
audit is enabled by default in Vite, Astro, and CLI builds. Diagnostics print sorted by page path and rule ID without modifying HTML or failing builds unless auditFailOn (--fail-on-audit) is set.
Checked rules cover:
- Missing, empty, multiple, or duplicate
<title>and meta description tags across included pages. - Missing or malformed
<html lang>tags and missing or multiple<h1>headings. - Invalid, conflicting, missing, relative, or cross-origin
canonicallinks (following Google canonical guidelines). - Malformed JSON-LD syntax (validates JSON parsing, arrays, and
@graphwithout asserting Schema.org rich-result eligibility). - Missing
altattributes on<img>elements (alt=""is accepted for decorative images). - Internal links, canonicals, or
hreflanglinks targeting knownnoindexpages, missing local build targets, or.htmlsuffixes whenprettyUrls: true. - Orphan non-home pages with zero incoming static links, non-reciprocal or missing self-referential
hreflangclusters, and discovery<link>consistency.
Diagnostics inspect local build artifacts only. They never send HTTP requests or verify live status codes, CDN rewrites, WAF rules, or response headers such as X-Robots-Tag.
Common recipes
Subpath deployment with replace mirrors
geo({
domain: 'https://example.com',
routeBasePath: '/docs/',
llmsMdMirrorStyle: 'replace',
generateRobots: false,
})
Multilingual sites (hreflang and hreflangFromHtml)
For subdomain deployments sharing identical path shapes, configure global templates:
geo({
domain: 'https://en.example.com',
hreflang: {
en: 'https://en.example.com/{path}',
'zh-CN': 'https://zh.example.com/{path}',
'x-default': 'https://en.example.com/{path}',
},
})
For path-prefixed locales (such as /about and /zh/about), declare alternates in each page's HTML <head> and enable hreflangFromHtml:
geo({
domain: 'https://example.com',
hreflangFromHtml: true,
})
Merchant root manifest (sku.md)
geo({
domain: 'https://shop.example.com',
skuMd: {
merchantName: 'Example Store',
summary: 'Independent tea catalog.',
catalog: [
{
label: 'All products',
url: 'https://shop.example.com/collections/all',
},
],
},
})
Mature site adding content-page Markdown mirrors only
If your site already maintains its own sitemap.xml, robots.txt, or llms.txt (or does not need an RSS feed), keep all existing SEO files intact and emit .md mirrors strictly for content sections:
geo({
domain: 'https://example.com',
generateFeed: false,
sitemapConflict: 'preserve',
fileConflict: 'preserve',
llmsMdMirrorInclude: ['docs/**', 'guides/**', 'blog/**'],
markdownStripSelectors: ['.toc', '.breadcrumb', '[data-promo]'],
})
You can also mark individual HTML blocks with data-geo-ignore so widgets or callouts inside <main> are excluded from generated .md mirrors:
<aside data-geo-ignore>Interactive widget omitted from .md mirrors</aside>
Note: When fileConflict: 'preserve' keeps a hand-written llms.txt alongside newly generated .md mirrors, the build emits a reminder warning because your hand-written llms.txt is not edited automatically.
Multilingual Astro site
Use vite-plugin-geo/astro (never the default 'vite-plugin-geo' Vite export) in astro.config.mjs:
// astro.config.mjs
import { defineConfig } from 'astro/config';
import geo from 'vite-plugin-geo/astro';
export default defineConfig({
site: 'https://example.com',
trailingSlash: 'always',
integrations: [
geo({
hreflangFromHtml: true,
feedIncludePatterns: ['blog/**', 'zh/blog/**'],
feedByLocale: true,
feedLanguage: 'en',
excludePatterns: ['**/404.html', '500.html'],
}),
],
});
Multilingual Astro notes:
trailingSlashalignment:vite-plugin-geo/astroautomatically follows Astro'sconfig.trailingSlash('always' -> 'always','never' -> 'never','ignore' -> 'preserve'), while keeping.mdmirrors at/about.mdand/zh/about.md(never/about/.md).- Using
@astrojs/sitemap: If you keep@astrojs/sitemapalongsidegeo(), placesitemap()first (integrations: [sitemap(), geo()]). By defaultvite-plugin-geopreserves@astrojs/sitemap's output; omitsitemap()(or setgenerateSitemap: true, sitemapConflict: 'overwrite') when you wantvite-plugin-geoto generatesitemap.xmlwithhreflangFromHtml: true. - Localized feeds:
feedIncludePatternsprevents landing pages from entering RSS feeds,feedByLocale: trueemits per-locale feeds instead of mixing languages under one<language>, andfeedLanguagesupplies the fallback language tag. - Multilingual
404.html: Root404.htmland500.htmlare excluded by default. If your site emits localized error pages (such aszh/404.htmloren/404.html), add'**/404.html'toexcludePatterns(andnoindex) so error pages do not appear in discovery outputs, while retaining rootdist/404.htmlfor static hosts. - Post-build script order: Run
astro build(which executesvite-plugin-geo/astroduringastro:build:done) -> any custom post-build HTML/asset scripts (if you invokevite-plugin-geo generatevia CLI instead of the integration, run it after HTML-modifying scripts) ->vite-plugin-geo verifylast so verification inspects the finaldist/output.
Static host Content-Type headers (_headers and vercel.json)
Many static hosts serve .md files as text/plain (or application/octet-stream) without charset=utf-8, and may serve feed.xml without application/rss+xml; charset=utf-8. Under X-Content-Type-Options: nosniff or on sites with non-ASCII text, browsers, feed readers, and AI agents can misrender or reject responses unless explicit Content-Type headers are configured.
Cloudflare Pages / Netlify (public/_headers):
/*.md
Content-Type: text/markdown; charset=utf-8
/feed.xml
Content-Type: application/rss+xml; charset=utf-8
On Cloudflare Pages, * matches across /, so /*.md covers nested files such as /zh/about.md. On Netlify or when using feedByLocale: true, add directory-scoped rules (such as /docs/*.md, /zh/*.md, and /zh/feed.xml) if your host matches * within a single path segment.
Vercel (vercel.json):
{
"headers": [
{
"source": "/(.*)\\.md$",
"headers": [
{ "key": "Content-Type", "value": "text/markdown; charset=utf-8" }
]
},
{
"source": "/feed.xml",
"headers": [
{ "key": "Content-Type", "value": "application/rss+xml; charset=utf-8" }
]
}
]
}
If feedByLocale: true emits localized feeds such as /zh/feed.xml, also add a "source": "/:locale/feed.xml" rule with Content-Type: application/rss+xml; charset=utf-8.
Deployment checklist
- Prevent host soft-404 responses: Static hosts such as Cloudflare Pages return
200 OKwith the home page for unknown paths unless404.htmlexists at the output root. Ensure your build emits404.htmland runvite-plugin-geo verifyin CI. - Avoid
closeBundleSitemap writers:vite-plugin-geoemits assets duringgenerateBundleand cannot prevent another plugin from overwritingsitemap.xmllater incloseBundle. Runvite-plugin-geo verifyin CI to catch post-bundle overwrites.
Specification contract
Specification review snapshot: 2026-08-12.
| Mechanism | Specification status | Plugin behavior |
|---|---|---|
llms.txt v2 (changes) |
Community proposal, not an IETF or W3C standard | Single-scope index, RFC 8288 / IANA describedby and Markdown alternate links, clean <main> / <article> mirrors |
robots.txt (RFC 9309) |
IETF Standards Track | Root /robots.txt only, user-file preservation, control-character and 500 KiB validation |
| Sitemap 0.9 | Industry protocol, not an IETF or W3C standard | URL sets, hreflang alternates, 50,000 URL / 50 MiB sharding, no ignored priority or changefreq tags |
| RSS 2.0.11 | Public specification | RSS 2.0 feed, Atom self link, canonical <guid>, no fabricated item pubDate |
humans.txt |
Informal community convention | Opt-in output containing only verified metadata |
SKU.md 1.0.0-beta (changelog) |
Experimental community proposal | Opt-in root /sku.md pure Markdown catalog under 65,536 UTF-8 bytes |
URL resolution rules
| Mode | HTML input | Public URL path | Markdown mirror |
|---|---|---|---|
prettyUrls: true, trailingSlash: 'never' (default) |
about.html or about/index.html |
/about |
/about.md |
prettyUrls: true, trailingSlash: 'always' |
about.html or about/index.html |
/about/ |
/about.md |
prettyUrls: true, trailingSlash: 'preserve' |
docs/index.html |
Matches page <link rel="canonical"> trailing slash |
/docs.md |
prettyUrls: false |
about.html |
/about.html |
/about.html.md (append) / /about.md (replace) |
| Home page | index.html |
/ (always; routeBasePath root /docs/ under 'always') |
/index.md |
Reviewed and intentionally not generated
| Proposal or mechanism | Review conclusion |
|---|---|
| IETF AIPREF | Vocabulary remains an active Internet-Draft (draft-ietf-aipref-vocab-06) and is not yet an RFC. |
| Cloudflare Content Signals | Vendor-specific directive rather than an interoperable IETF standard. |
| W3C TDM Reservation Protocol | W3C Community Group Final Report, not a W3C Recommendation. |
ai.txt |
Fragmented community drafts without stable cross-vendor adoption. |
Shopify agents.md |
Platform-specific storefront convention unsuitable as a generic Vite default. |
| WebMCP Draft Community Group Report | Browser runtime API draft rather than a static build artifact. |
Contributing
Issues and pull requests are welcome at github.com/maxlee/vite-plugin-geo.
Repository layout:
vite-plugin-geo/
├── src/ # Runtime entry points, core pipeline, audit/verify, and .d.ts types
├── tests/ # Unit and real-framework integration tests (Vite 7/8 and Astro 7)
├── scripts/ # Registry metadata and packed-tarball consumer verifiers
└── .github/ # GitHub Actions CI workflows
Local development uses Bun for test execution and Node.js (^20.19.0 || >=22.12.0) for consumer matrix verification:
# Install dependencies
bun install
# Run the test suite and coverage
bun test
bun test --coverage
# Validate Vite Plugin Registry schema metadata
bun run verify:registry-metadata
# Verify packed tarball against real Vite 7/8, Astro 7, and Vite+ 1.x consumers (plus TypeScript checks)
bun run verify:consumers
# Inspect the npm publish file list
npm run pack:dry-run
Follow Conventional Commits (feat:, fix:, docs:, test:, chore:) when submitting pull requests, and ensure git diff --check reports no whitespace errors.
Changelog
See CHANGELOG.md for release notes and migration guides.
License
MIT maxlee