npm.io
0.4.0 • Published 12h agoCLI

vite-plugin-geo

Licence
MIT
Version
0.4.0
Deps
2
Size
376 kB
Vulns
0
Weekly
0

vite-plugin-geo

npm version CI Node.js License: MIT

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

  • Sitemap 0.9 generation and splitting. Builds URL sets from emitted HTML with configurable trailingSlash normalization, splits files automatically above 50,000 URLs or sitemapMaxBytes (up to 50 MiB), and coexists with @astrojs/sitemap.
  • RFC 9309 robots.txt handling. Preserves hand-written robots.txt byte-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 with feedByLocale) with an Atom self link, include/exclude filters, item caps, language override, and idempotent <link rel="alternate" type="application/rss+xml"> injection.
  • llms.txt v2 and Markdown mirrors. Injects rel="describedby" and rel="alternate" type="text/markdown" links, scopes mirrors with llmsMdMirrorInclude / llmsMdMirrorExclude, and extracts clean <main> or single-<article> prose (with GFM tables, <details>/<summary>, data-geo-ignore, markdownStripSelectors, and single-H1 enforcement) into .md mirrors without navigation or form noise.
  • Multilingual hreflang support. Populates Sitemap xhtml:link alternates from global route templates or per-page HTML <link rel="alternate" hreflang="..."> tags (hreflangFromHtml).
  • Optional humans.txt and sku.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 final dist/ 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-plus itself 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:

  • distDir defaults to Vite's resolved build.outDir, and routeBasePath defaults to Vite's base.
  • The plugin sets apply: 'build' and runs in generateBundle (enforce: 'post') via this.emitFile, so build.write: false is respected and plugin outputs take precedence over duplicate files in publicDir while still respecting fileConflict, sitemapConflict, and generateRobots for 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' so vp check, vp lint, and vp fmt skip plugin factory execution during metadata resolution (VP_RESOLVING_CONFIG_METADATA=1).
  • Use vp build for web application builds (which executes the Vite + Rolldown pipeline). vp pack runs tsdown for libraries and standalone binaries and does not produce HTML pages.
  • Because vite-plus maps vite to @voidzero-dev/vite-plus-core@1.x rather than vite@7/8, keep the standard Vite+ overrides (npm / pnpm) and pnpm.peerDependencyRules generated by vp create or vp migrate.
  • When running generateHumans: true in a Vite+ project whose package.json lists vite-plus (without a direct vite entry), humans.txt records vite-plus under Components:.
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 integrations must import from 'vite-plugin-geo/astro' (import geo from 'vite-plugin-geo/astro'). Passing the default 'vite-plugin-geo' Vite plugin export into integrations throws an explicit configuration error during astro:config:setup.

// 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 prettyUrls is not explicitly configured and Astro build.format is 'file', vite-plugin-geo/astro disables prettyUrls so public links match .html outputs.
  • When trailingSlash is not explicitly configured, vite-plugin-geo/astro automatically aligns with Astro's config.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 from sitemap.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.txt and llms.txt to the detected Sitemap index or file (including custom filenameBase names).

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 canonical links (following Google canonical guidelines).
  • Malformed JSON-LD syntax (validates JSON parsing, arrays, and @graph without asserting Schema.org rich-result eligibility).
  • Missing alt attributes on <img> elements (alt="" is accepted for decorative images).
  • Internal links, canonicals, or hreflang links targeting known noindex pages, missing local build targets, or .html suffixes when prettyUrls: true.
  • Orphan non-home pages with zero incoming static links, non-reciprocal or missing self-referential hreflang clusters, 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:

  • trailingSlash alignment: vite-plugin-geo/astro automatically follows Astro's config.trailingSlash ('always' -> 'always', 'never' -> 'never', 'ignore' -> 'preserve'), while keeping .md mirrors at /about.md and /zh/about.md (never /about/.md).
  • Using @astrojs/sitemap: If you keep @astrojs/sitemap alongside geo(), place sitemap() first (integrations: [sitemap(), geo()]). By default vite-plugin-geo preserves @astrojs/sitemap's output; omit sitemap() (or set generateSitemap: true, sitemapConflict: 'overwrite') when you want vite-plugin-geo to generate sitemap.xml with hreflangFromHtml: true.
  • Localized feeds: feedIncludePatterns prevents landing pages from entering RSS feeds, feedByLocale: true emits per-locale feeds instead of mixing languages under one <language>, and feedLanguage supplies the fallback language tag.
  • Multilingual 404.html: Root 404.html and 500.html are excluded by default. If your site emits localized error pages (such as zh/404.html or en/404.html), add '**/404.html' to excludePatterns (and noindex) so error pages do not appear in discovery outputs, while retaining root dist/404.html for static hosts.
  • Post-build script order: Run astro build (which executes vite-plugin-geo/astro during astro:build:done) -> any custom post-build HTML/asset scripts (if you invoke vite-plugin-geo generate via CLI instead of the integration, run it after HTML-modifying scripts) -> vite-plugin-geo verify last so verification inspects the final dist/ 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 OK with the home page for unknown paths unless 404.html exists at the output root. Ensure your build emits 404.html and run vite-plugin-geo verify in CI.
  • Avoid closeBundle Sitemap writers: vite-plugin-geo emits assets during generateBundle and cannot prevent another plugin from overwriting sitemap.xml later in closeBundle. Run vite-plugin-geo verify in 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

Keywords