# vite-plugin-geo

> Vite, Vite+, and Astro plugin to generate sitemap.xml, llms.txt, robots.txt, and optional GEO companion files.

Latest version **0.4.0** (published 2026-11-21) · MIT license · 0 weekly downloads

## Install

```sh
npm install vite-plugin-geo
pnpm add vite-plugin-geo
yarn add vite-plugin-geo
bun add vite-plugin-geo
```

Provides the command `vite-plugin-geo`.

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.4.0 |
| Published | 2026-11-21 |
| First published | 2026-03-10 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | ^20.19.0 \|\| >=22.12.0 |
| Dependencies | 2 |
| Unpacked size | 375.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | maxlee |
| Maintainers | maxlee |
| Keywords | vite, vite-plugin, vite-plus, viteplus, geo, seo, sitemap, robots, llms, sku.md |

## Links

- npm: https://www.npmjs.com/package/vite-plugin-geo
- Repository: https://github.com/maxlee/vite-plugin-geo
- Homepage: https://github.com/maxlee/vite-plugin-geo#readme
- Issues: https://github.com/maxlee/vite-plugin-geo/issues
- npm.io page: https://npm.io/package/vite-plugin-geo

## Dependencies (2)

- [parse5](https://npm.io/package/parse5.md) 8.0.1
- [turndown](https://npm.io/package/turndown.md) 7.2.4

## Alternatives

- [@mdxeditor/editor](https://npm.io/package/@mdxeditor/editor.md) — 962.4K weekly downloads
- [mmdb-lib](https://npm.io/package/mmdb-lib.md) — 680.9K weekly downloads
- [playcanvas](https://npm.io/package/playcanvas.md) — 36.2K weekly downloads
- [@glw907/cairn-cms](https://npm.io/package/@glw907/cairn-cms.md) — 967 weekly downloads
- [markdown-to-confluence](https://npm.io/package/markdown-to-confluence.md) — 103 weekly downloads

## Recent versions

- 0.4.0 (latest) — 2026-11-21
- 0.3.0 — 2026-11-14
- 0.2.2 — 2026-11-05
- 0.2.1 — 2026-11-04
- 0.2.0 — 2026-11-01
- 0.1.5 — 2026-10-30
- 0.1.4 — 2026-08-17
- 0.1.3 — 2026-08-08
- 0.1.2 — 2026-07-29
- 0.1.1 — 2026-07-27
- 0.0.7 — 2026-06-18
- 0.0.6 — 2026-03-12
- 0.0.5 — 2026-03-12
- 0.0.4 — 2026-03-11
- 0.0.3 — 2026-03-11
- … 2 more at https://npm.io/package/vite-plugin-geo/versions

## README

# vite-plugin-geo

[![npm version](https://img.shields.io/npm/v/vite-plugin-geo.svg)](https://www.npmjs.com/package/vite-plugin-geo)
[![CI](https://github.com/maxlee/vite-plugin-geo/actions/workflows/ci.yml/badge.svg)](https://github.com/maxlee/vite-plugin-geo/actions/workflows/ci.yml)
[![Node.js](https://img.shields.io/node/v/vite-plugin-geo.svg)](./package.json)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)

English | [简体中文](./README.zh-CN.md)

Post-build discovery file generator and static verifier for Vite, [Vite+](https://viteplus.dev/), 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](#features)
- [Requirements](#requirements)
- [Installation](#installation)
- [Quick start](#quick-start)
  - [Vite](#vite)
  - [Vite+](#vite-1)
  - [Astro](#astro)
- [Generated files](#generated-files)
- [Configuration](#configuration)
- [Astro sitemap compatibility](#astro-sitemap-compatibility)
- [CLI and CI verification](#cli-and-ci-verification)
- [Build diagnostics](#build-diagnostics)
- [Common recipes](#common-recipes)
- [Specification contract](#specification-contract)
- [Contributing](#contributing)
- [Changelog](#changelog)
- [License](#license)

## 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

```bash
npm install -D vite-plugin-geo
```

```bash
pnpm add -D vite-plugin-geo
```

```bash
yarn add -D vite-plugin-geo
```

```bash
bun add -d vite-plugin-geo
```

In Vite+ workspaces:

```bash
vp add -D vite-plugin-geo
```

## Quick start

### Vite

Add the default plugin export to `vite.config.js`:

```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:

```js
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+](https://viteplus.dev/) (`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:

```ts
// 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`.

#### Option 1: Native Astro integration (recommended)

```js
// 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

```json
{
  "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:

```text
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. |

<details>
<summary>Advanced options</summary>

| 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. |

</details>

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):

```js
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'`:

```js
geo({
  generateSitemap: true,
  sitemapConflict: 'overwrite',
  sitemapUrl: 'sitemap.xml',
})
```

## CLI and CI verification

Run generation or post-build verification directly from the command line:

```bash
# 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:

```bash
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`:

```bash
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:

```yaml
- 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
```

<details>
<summary>Full CLI flag reference</summary>

`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. |

</details>

## 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](https://developers.google.com/search/docs/crawling-indexing/consolidate-duplicate-urls)).
- 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

```js
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:

```js
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`:

```js
geo({
  domain: 'https://example.com',
  hreflangFromHtml: true,
})
```

### Merchant root manifest (`sku.md`)

```js
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:

```js
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:

```html
<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`:

```js
// 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`):**

```text
/*.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`):**

```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](https://llmstxt.org/) ([changes](https://llmstxt.org/changes.html)) | Community proposal, not an IETF or W3C standard | Single-scope index, [RFC 8288](https://www.rfc-editor.org/rfc/rfc8288) / [IANA](https://www.iana.org/assignments/link-relations/link-relations.xhtml) `describedby` and Markdown `alternate` links, clean `<main>` / `<article>` mirrors |
| [`robots.txt` (RFC 9309)](https://www.rfc-editor.org/rfc/rfc9309) | IETF Standards Track | Root `/robots.txt` only, user-file preservation, control-character and 500 KiB validation |
| [Sitemap 0.9](https://www.sitemaps.org/protocol.html) | 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](https://www.rssboard.org/rss-specification) | Public specification | RSS 2.0 feed, Atom `self` link, canonical `<guid>`, no fabricated item `pubDate` |
| [`humans.txt`](https://humanstxt.org/Standard.html) | Informal community convention | Opt-in output containing only verified metadata |
| [SKU.md `1.0.0-beta`](https://sku.md/spec/1.0.0-beta/sku-md-spec.md) ([changelog](https://sku.md/spec/1.0.0-beta/changelog.md)) | 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](https://datatracker.ietf.org/group/aipref/) | Vocabulary remains an active Internet-Draft (`draft-ietf-aipref-vocab-06`) and is not yet an RFC. |
| [Cloudflare Content Signals](https://developers.cloudflare.com/bots/additional-configurations/managed-robots-txt/) | Vendor-specific directive rather than an interoperable IETF standard. |
| [W3C TDM Reservation Protocol](https://www.w3.org/community/reports/tdmrep/CG-FINAL-tdmrep-20240510/) | W3C Community Group Final Report, not a W3C Recommendation. |
| `ai.txt` | Fragmented community drafts without stable cross-vendor adoption. |
| [Shopify `agents.md`](https://shopify.dev/changelog/customize-llmstxt-llms-fulltxt-and-agentsmd) | Platform-specific storefront convention unsuitable as a generic Vite default. |
| [WebMCP Draft Community Group Report](https://webmachinelearning.github.io/webmcp/) | Browser runtime API draft rather than a static build artifact. |

## Contributing

Issues and pull requests are welcome at [github.com/maxlee/vite-plugin-geo](https://github.com/maxlee/vite-plugin-geo).

Repository layout:

```text
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](https://bun.sh/) for test execution and Node.js (`^20.19.0 || >=22.12.0`) for consumer matrix verification:

```bash
# 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](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `docs:`, `test:`, `chore:`) when submitting pull requests, and ensure `git diff --check` reports no whitespace errors.

## Changelog

See [CHANGELOG.md](./CHANGELOG.md) for release notes and migration guides.

## License

[MIT](./LICENSE) © maxlee

---
_Source: https://npm.io/package/vite-plugin-geo · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
