SDK

Use the root SDK when your script already knows the built output folder.

Install

Install OpenNav before importing OpenNavStaticSite.

npm install @opennav-ai/opennav

pnpm add @opennav-ai/opennav

yarn add @opennav-ai/opennav

bun add @opennav-ai/opennav

Quick start

import { OpenNavStaticSite } from "@opennav-ai/opennav";

const result = await new OpenNavStaticSite({
  siteName: "Example Docs",
  siteUrl: "https://example.com",
  outputDirectory: "dist",
}).build();

if (result.isErr()) {
  console.error(result.error.message);
  process.exit(1);
}

console.log(result.value);

Full example

import { OpenNavStaticSite } from "@opennav-ai/opennav";

const result = await new OpenNavStaticSite({
  siteName: "Example Docs",
  siteUrl: "https://example.com",
  outputDirectory: "dist",
  preset: "astro",
  platform: "cloudflare-pages",
  contentExtraction: {
    stripLayout: true,
  },
  accessGuidance: {
    contentSignals: {
      search: "allow",
      aiInput: "allow",
      aiTrain: "disallow",
    },
  },
}).build({ dryRun: true });

if (result.isErr()) {
  console.error(result.error.message);
  process.exit(1);
}

console.log(result.value);

`OpenNavStaticSite(options)`

Creates a static-site runner for one built output folder.

interface OpenNavStaticSiteOptions {
  readonly siteName: string;
  readonly siteUrl: string;
  readonly outputDirectory: string;
  readonly preset?: "astro" | "next-export";
  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";
    };
  };
}

`siteName`

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

`siteUrl`

Required. Public absolute URL used for generated links and manifest URLs. The value should include the protocol and host, such as https://example.com.

`outputDirectory`

Required. Built static output folder OpenNav scans and updates. In most projects, pass an output-directory-relative path from the script’s working directory, such as dist, out, or apps/docs/dist.

OpenNav reads from and writes to this folder only. Relative paths are resolved by the calling script from the current working directory.

`preset`

Optional. Framework hint for static-folder conventions.

Supported values are "astro" and "next-export". When omitted, OpenNav treats outputDirectory as a generic static site 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 the Cloudflare Pages _headers file by default. That file tells Cloudflare Pages to serve generated Markdown as text/markdown, generated llms indexes as text/plain, and the OpenNav manifest as application/json. It 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 without parsing the HTML body first.

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

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

const result = await new OpenNavStaticSite({
  siteName: "Example Docs",
  siteUrl: "https://example.com",
  outputDirectory: "dist",
  contentExtraction: {
    stripLayout: true,
  },
}).build();

`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 _headers unless you opt out.

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

const result = await new OpenNavStaticSite({
  siteName: "Example Docs",
  siteUrl: "https://example.com",
  outputDirectory: "dist",
  platform: "cloudflare-pages",
  staticHeaders: {
    enabled: false,
  },
}).build();

`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 robots.txt inside outputDirectory.

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

`accessGuidance.contentSignals`

Optional. Content-use preferences OpenNav writes into 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.

`build(options)`

Runs OpenNav against the configured output folder.

interface OpenNavStaticSiteBuildOptions {
  readonly dryRun?: boolean;
}

`dryRun`

Optional. Set to true to preview created, modified, skipped, and warning paths without changing files.