Astro

Astro static sites can run OpenNav after astro build through the Astro integration.

Install

Install OpenNav in your Astro project.

npm install @opennav-ai/opennav

pnpm add @opennav-ai/opennav

yarn add @opennav-ai/opennav

bun add @opennav-ai/opennav

Quick start

import { defineConfig } from "astro/config";
import { OpenNavAstro } from "@opennav-ai/opennav/astro";

export default defineConfig({
  site: "https://example.com",
  integrations: [
    OpenNavAstro({
      siteName: "Example Docs",
      mode: "static",
    }),
  ],
});

Full example

import { defineConfig } from "astro/config";
import { OpenNavAstro } from "@opennav-ai/opennav/astro";

export default defineConfig({
  site: "https://example.com",
  integrations: [
    OpenNavAstro({
      siteName: "Example Docs",
      siteUrl: "https://example.com",
      mode: "static",
      platform: "cloudflare-pages",
      contentExtraction: {
        stripLayout: true,
      },
      accessGuidance: {
        contentSignals: {
          search: "allow",
          aiInput: "allow",
          aiTrain: "disallow",
        },
      },
    }),
  ],
});

If siteUrl is omitted, the integration uses Astro’s top-level site value. Static mode is the supported Astro integration mode and is used when mode is omitted.

`OpenNavAstro(options)`

Runs OpenNav after astro build finishes writing static output.

interface OpenNavAstroOptions {
  readonly siteName: string;
  readonly siteUrl?: string;
  readonly mode?: "static";
  readonly platform?: "cloudflare-pages";
  readonly contentExtraction?: {
    readonly stripLayout?: boolean;
  };
  readonly staticHeaders?: {
    readonly enabled: boolean;
  };
  readonly accessGuidance?: {
    readonly contentSignals?: {
      readonly search?: "allow" | "disallow";
      readonly aiInput?: "allow" | "disallow";
      readonly aiTrain?: "allow" | "disallow";
    };
  };
}

Property	Type	Description
`siteName`	`string`	Required. Human-readable site or docs name written into generated OpenNav files, including `dist/llms.txt`, page Markdown files, and `dist/.well-known/opennav.json`.
`siteUrl`	`string`	Optional when Astro’s top-level `site` config is set. Public absolute URL used for generated links and manifest URLs.
`mode`	`”static”`	Optional. Static mode is the supported Astro integration mode and is used when `mode` is omitted.
`accessGuidance`	`OpenNavAccessGuidance`	Optional. Controls whether OpenNav creates or updates its managed Content Signals block in `dist/robots.txt`.
`platform`	`”cloudflare-pages”`	Optional. Enables platform-specific output. For Cloudflare Pages, OpenNav creates or updates `dist/_headers` by default.
`contentExtraction`	`{ stripLayout?: boolean }`	Optional. Controls whether generated Markdown keeps the whole HTML body or strips the documented layout elements first.
`staticHeaders`	`{ enabled: boolean }`	Optional. Overrides the platform default for response-header artifacts such as Cloudflare Pages `_headers`.

`siteName`

Required. Human-readable site or docs name written into generated OpenNav files, including dist/llms.txt, page Markdown files, and dist/.well-known/opennav.json.

`siteUrl`

Optional when Astro’s top-level site config is set. Public absolute URL used for generated links and manifest URLs.

export default defineConfig({
  site: "https://example.com",
  integrations: [
    OpenNavAstro({
      siteName: "Example Docs",
    }),
  ],
});

Pass siteUrl directly when the deployed URL should come from OpenNav instead of Astro config.

`mode`

Optional. Only "static" is supported today, and OpenNav uses it when mode is omitted.

OpenNav aborts the Astro build with a typed error when Astro reports server output, because static mode reads and updates the generated dist folder.

`platform`

Optional. Static hosting platform for platform-specific generated files.

Supported values are "cloudflare-pages". When platform: "cloudflare-pages" is passed, OpenNav creates or updates dist/_headers by default so Cloudflare Pages serves generated Markdown, llms files, and the OpenNav manifest with explicit response content types. The same _headers block also adds per-page HTTP Link headers to HTML routes so agents can discover each page’s Markdown alternate and the root llms.txt index from response headers.

Omit platform for a generic Astro static build. More platform values will be added as OpenNav gains first-class support for additional static hosts.

export default defineConfig({
  site: "https://example.com",
  integrations: [
    OpenNavAstro({
      siteName: "Example Docs",
      platform: "cloudflare-pages",
    }),
  ],
});

`contentExtraction`

Optional. Controls how OpenNav reads built HTML pages before creating generated Markdown page artifacts and llms-full.txt.

When omitted, OpenNav preserves the current conservative behavior: it converts the whole HTML <body> to Markdown. Set stripLayout to true to remove the documented fixed list of layout elements before Markdown conversion.

See the content extraction reference for the exact stripped elements and the cases where you should leave this unset.

This first version uses a fixed strip list. Future versions are expected to add more granular HTML element controls, such as tag-level, class-level, or selector-level strip and preserve rules.

export default defineConfig({
  site: "https://example.com",
  integrations: [
    OpenNavAstro({
      siteName: "Example Docs",
      contentExtraction: {
        stripLayout: true,
      },
    }),
  ],
});

`contentExtraction.stripLayout`

Optional. Defaults to false.

When true, OpenNav still starts from the whole HTML <body>, but removes the declared layout elements before converting that body to Markdown.

`staticHeaders`

Optional. Controls platform response-header artifacts such as Cloudflare Pages _headers.

When omitted, OpenNav uses the configured platform default. The current Cloudflare Pages default is enabled, so platform: "cloudflare-pages" creates or updates dist/_headers unless you opt out.

If an existing caller-owned dist/_headers route overlaps OpenNav’s generated routes, OpenNav leaves dist/_headers untouched and reports a warning.

export default defineConfig({
  site: "https://example.com",
  integrations: [
    OpenNavAstro({
      siteName: "Example Docs",
      platform: "cloudflare-pages",
      staticHeaders: {
        enabled: false,
      },
    }),
  ],
});

`staticHeaders.enabled`

Required inside staticHeaders. Set to false to keep platform metadata such as platform: "cloudflare-pages" without creating or editing the platform header file. Set to true to explicitly request the platform header file. When true, platform must also be configured because each host has its own header-file format.

`accessGuidance`

Optional. Controls whether OpenNav creates or updates its managed Content Signals block in dist/robots.txt.

When omitted, OpenNav does not create or edit robots.txt for access guidance.

`accessGuidance.contentSignals`

Optional. Content-use preferences OpenNav writes into dist/robots.txt.

At least one nested field must be configured before OpenNav creates or updates its managed Content Signals block.

`search`

Optional. Writes search=yes for “allow” or search=no for “disallow”. When omitted, OpenNav does not express a search-use preference.

`aiInput`

Optional. Writes ai-input=yes for “allow” or ai-input=no for “disallow”. When omitted, OpenNav does not express an AI-input preference.

`aiTrain`

Optional. Writes ai-train=yes for “allow” or ai-train=no for “disallow”. When omitted, OpenNav does not express an AI-training preference.

Server-Side Support

Astro server output is the next open-source track. This is the future of agent-ready websites: the same route can serve HTML to people and Markdown to agents through content negotiation.

Planned launch shape:

import { defineConfig } from "astro/config";
import { OpenNavAstroServer } from "@opennav-ai/opennav/astro";

export default defineConfig({
  output: "server",
  integrations: [
    OpenNavAstroServer({
      siteName: "Example Docs",
      markdown: {
        mode: "content-negotiation",
        routes: ["/docs/**", "/blog/**"],
      },
    }),
  ],
});

When a request prefers text/markdown, OpenNav will return an agent-readable Markdown representation from the same URL. Browser requests still receive HTML, and responses include Vary: Accept so caches keep both representations correct.

See the server-side framework roadmap for the shared Astro and Next.js launch shape.