---
title: "Sitemaps"
description: "Generate sitemap.xml, sitemap.md, and docs/sitemap.md for crawlers, agents, and static exports"
canonical_url: "https://docs.farming-labs.dev/docs/customization/sitemaps"
markdown_url: "https://docs.farming-labs.dev/docs/customization/sitemaps.md"
last_updated: "2018-10-20"
agent:
  tokenBudget: 950
  task: "Generate and verify XML and Markdown sitemaps for runtime and static docs deployments."
  outcome: "Canonical sitemap routes or generated files list the expected docs pages with valid links and configured freshness metadata."
  appliesTo:
    framework:
      - "nextjs"
      - "tanstackstart"
      - "sveltekit"
      - "astro"
      - "nuxt"
    version:
      - ">=0.2.60"
    package:
      - "@farming-labs/docs"
  prerequisites:
    - "The docs content tree and public base URL are configured."
    - "Decide whether the deployment serves runtime routes or needs generated public files."
  files:
    - "docs.config.ts"
    - "docs.config.tsx"
    - "src/lib/docs.config.ts"
    - ".farming-labs/sitemap-manifest.json"
    - "public/sitemap.xml"
    - "public/sitemap.md"
    - "public/docs/sitemap.md"
    - "static/sitemap.xml"
    - "static/sitemap.md"
    - "static/docs/sitemap.md"
  commands:
    - run: "pnpm exec docs sitemap generate"
      description: "Generate the manifest and static sitemap artifacts."
    - run: "pnpm exec docs sitemap generate --check"
      description: "Fail when committed sitemap artifacts are stale."
  sideEffects:
    - "Static generation writes the sitemap manifest and public sitemap files."
  verification:
    - run: "pnpm exec docs sitemap generate --check"
      expect: "Generated sitemap artifacts match the current docs tree."
    - description: "Fetch sitemap.xml, sitemap.md, /docs/sitemap.md, and /.well-known/sitemap.md from a running site."
      expect: "Each route returns the configured format and links to known canonical docs pages."
  rollback:
    - "Restore the previous sitemap config and regenerate or remove only the sitemap artifacts it owned."
  failureModes:
    - symptom: "The check reports stale generated files."
      resolution: "Regenerate from the same docs config and commit the manifest and public output together."
    - symptom: "Sitemap URLs use the wrong origin or prefix."
      resolution: "Correct sitemap.baseUrl or routePrefix, regenerate, and verify every advertised alias."
---

<!-- farming-labs:agent-contract:start -->
## Agent Contract

Task: Generate and verify XML and Markdown sitemaps for runtime and static docs deployments.
Outcome: Canonical sitemap routes or generated files list the expected docs pages with valid links and configured freshness metadata.

### Applies To

- Framework: `nextjs`, `tanstackstart`, `sveltekit`, `astro`, `nuxt`
- Version: `>=0.2.60`
- Package: `@farming-labs/docs`

### Prerequisites

- The docs content tree and public base URL are configured.
- Decide whether the deployment serves runtime routes or needs generated public files.

### Files

- `docs.config.ts`
- `docs.config.tsx`
- `src/lib/docs.config.ts`
- `.farming-labs/sitemap-manifest.json`
- `public/sitemap.xml`
- `public/sitemap.md`
- `public/docs/sitemap.md`
- `static/sitemap.xml`
- `static/sitemap.md`
- `static/docs/sitemap.md`

### Commands

- `pnpm exec docs sitemap generate` — Generate the manifest and static sitemap artifacts.
- `pnpm exec docs sitemap generate --check` — Fail when committed sitemap artifacts are stale.

### Side Effects

- Static generation writes the sitemap manifest and public sitemap files.

### Verification

- Run `pnpm exec docs sitemap generate --check`
  - Expected: Generated sitemap artifacts match the current docs tree.
- Fetch sitemap.xml, sitemap.md, /docs/sitemap.md, and /.well-known/sitemap.md from a running site.
  - Expected: Each route returns the configured format and links to known canonical docs pages.

### Rollback

- Restore the previous sitemap config and regenerate or remove only the sitemap artifacts it owned.

### Failure Modes

- The check reports stale generated files. — Recovery: Regenerate from the same docs config and commit the manifest and public output together.
- Sitemap URLs use the wrong origin or prefix. — Recovery: Correct sitemap.baseUrl or routePrefix, regenerate, and verify every advertised alias.
<!-- farming-labs:agent-contract:end -->

# Sitemaps

## Sitemaps task

Task: Generate and verify XML and Markdown sitemaps for runtime and static docs deployments.

Expected result: Canonical sitemap routes or generated files list the expected docs pages with valid links and configured freshness metadata.

Exact implementation:

```bash title="terminal"
pnpm exec docs sitemap generate
pnpm exec docs robots generate
```
## Sitemaps prerequisites

- The docs content tree and public base URL are configured.
- Decide whether the deployment serves runtime routes or needs generated public files.
- Applies to framework nextjs, tanstackstart, sveltekit, astro, nuxt; version >=0.2.60; package @farming-labs/docs.

## Sitemaps verification

- Run pnpm exec docs sitemap generate --check. Expected: Generated sitemap artifacts match the current docs tree.
- Fetch sitemap.xml, sitemap.md, /docs/sitemap.md, and /.well-known/sitemap.md from a running site. Expected: Each route returns the configured format and links to known canonical docs pages.
- Failure: The check reports stale generated files.
- Recovery: Regenerate from the same docs config and commit the manifest and public output together.
- Rollback: Restore the previous sitemap config and regenerate or remove only the sitemap artifacts it owned.

## Sitemaps agent guidance

Use this page when the task is to customize or troubleshoot generated sitemaps. Runtime sitemap
routes are enabled by default; use `sitemap: false` only when a project must opt out.

Default public routes:
- `/sitemap.xml`
- `/sitemap.md`
- `/docs/sitemap.md`
- `/.well-known/sitemap.md`

Static export command:
- `pnpm exec docs sitemap generate`

Pair with `pnpm exec docs robots generate` when the static host should also publish an explicit
crawler and AI-agent access policy at `/robots.txt`.

The command writes `.farming-labs/sitemap-manifest.json` plus public sitemap files unless
`--manifest-only` is used. Lastmod dates come from `git log -1` for each page source path first,
then filesystem mtime as a fallback. Preloaded adapters also use the manifest as the stable source
for JSON-LD `dateModified`.

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).