[Skip to content](#_top)
[ OpenNav AI](https://opennav.ai/)
Search CtrlK
Cancel
[Docs](https://docs.opennav.ai/index.md)
[Quick Start](https://docs.opennav.ai/getting-started/index.md)
[SDK](https://docs.opennav.ai/sdk/index.md)
[OpenNav AI on X](https://x.com/OpenNavAI)
[Joshua Bellew on X](https://x.com/manofyear93)
[Email Joshua Bellew](mailto:joshua@opennav.ai)
- Start Here
- [Overview](https://docs.opennav.ai/index.md)
- [How It Works](https://docs.opennav.ai/how-it-works/index.md)
- [Getting Started](https://docs.opennav.ai/getting-started/index.md)
- Use OpenNav
- [CLI](https://docs.opennav.ai/cli/index.md)
- [SDK](https://docs.opennav.ai/sdk/index.md)
- Frameworks
- [Astro](https://docs.opennav.ai/frameworks/astro/index.md)
- [Next.js](https://docs.opennav.ai/frameworks/next/index.md)
- [Server-side frameworks Soon](https://docs.opennav.ai/frameworks/server-side/index.md)
- Platforms
- [Cloudflare](https://docs.opennav.ai/platforms/cloudflare/index.md)
- Reference
- [Generated Files](https://docs.opennav.ai/reference/generated-files/index.md)
- [Content Extraction](https://docs.opennav.ai/reference/content-extraction/index.md)
- [Access Guidance](https://docs.opennav.ai/reference/access-guidance/index.md)
- External
- [AcceptMarkdown](https://acceptmarkdown.com/)
- [Cloudflare Agent Readiness](https://blog.cloudflare.com/agent-readiness/)
- [Is It Agent Ready?](https://isitagentready.com/)
[OpenNav AI on X](https://x.com/OpenNavAI)
[Joshua Bellew on X](https://x.com/manofyear93)
[Email Joshua Bellew](mailto:joshua@opennav.ai)
On this page
- [Overview](#_top)
- [Build Flow](#build-flow)
- [Files And Edits OpenNav Plans](#files-and-edits-opennav-plans)
- [Page Markdown](#page-markdown)
- [HTML Resource Links](#html-resource-links)
- [Platform Headers](#platform-headers)
- [llms.txt And llms-full.txt](#llmstxt-and-llms-fulltxt)
- [opennav.json](#opennavjson)
- [robots.txt](#robotstxt)
- [Files OpenNav Skips](#files-opennav-skips)
- [What OpenNav Does Not Do](#what-opennav-does-not-do)
## On this page
- [Overview](#_top)
- [Build Flow](#build-flow)
- [Files And Edits OpenNav Plans](#files-and-edits-opennav-plans)
- [Page Markdown](#page-markdown)
- [HTML Resource Links](#html-resource-links)
- [Platform Headers](#platform-headers)
- [llms.txt And llms-full.txt](#llmstxt-and-llms-fulltxt)
- [opennav.json](#opennavjson)
- [robots.txt](#robotstxt)
- [Files OpenNav Skips](#files-opennav-skips)
- [What OpenNav Does Not Do](#what-opennav-does-not-do)
# How It Works
OpenNav runs after your normal static site build. It reads the finished output folder, creates agent-readable files beside the generated HTML, and leaves the folder ready to deploy to the same host or CDN you already use.
It does not call an LLM, crawl the public internet, edit your source files, or send your site content to an external service.
## Build Flow
[Section titled “Build Flow”](#build-flow)
1. You build your site into a folder such as `dist`, `out`, or `build`.
2. OpenNav scans that folder for HTML pages, Markdown pages, and `robots.txt`.
3. OpenNav creates Markdown mirrors, `llms` indexes, compatibility metadata, safe HTML resource links, optional Content Signals guidance, and optional platform header files inside the same output folder.
4. Your existing deploy step publishes the finished folder.
When you run with `--dry-run` or SDK `dryRun: true`, OpenNav returns the same planned created, modified, skipped, and warning paths without writing the output folder.
## Files And Edits OpenNav Plans
[Section titled “Files And Edits OpenNav Plans”](#files-and-edits-opennav-plans)
OpenNav writes a predictable set of files and page edits inside the configured output folder.
| File or edit | What it does |
| --- | --- |
| `llms.txt` | Root agent-readable site index with links to readable Markdown page endpoints. |
| `.well-known/llms.txt` | Well-known copy of the root site index. |
| `llms-full.txt` | Combined readable page content, capped at complete page blocks when the configured token limit is reached. |
| `.well-known/llms-full.txt` | Well-known copy of the combined readable content file. |
| `.well-known/opennav.json` | Compatibility manifest with generated artifact paths, resource-link support, Content Signals support, and the build fingerprint. |
| `*.md` page artifacts | Markdown mirrors for HTML pages, such as `docs/api/index.md`. |
| `*.html` page edits | Safe `` resource links pointing to each page’s Markdown mirror and the root `llms.txt`. |
| `robots.txt` | Optional Content Signals guidance when `accessGuidance` is configured. |
| `_headers` | Optional platform response-header artifact. Cloudflare Pages creates this by default when `platform: "cloudflare-pages"` or `--platform cloudflare-pages` is configured. |
Generated files include an OpenNav build marker so later runs can safely update the files OpenNav owns without claiming unrelated user files.
## Page Markdown
[Section titled “Page Markdown”](#page-markdown)
For every supported HTML page, OpenNav creates a matching `.md` endpoint. The path mirrors the page route:
```txt
index.html -> index.mddocs/index.html -> docs/index.mddocs/api.html -> docs/api.mddocs/reference/index.html -> docs/reference/index.md
```
By default, OpenNav converts the whole HTML `` to Markdown. That keeps the static behavior conservative for sites with custom HTML structures. Callers can enable `contentExtraction.stripLayout` to remove the documented layout elements before Markdown conversion.
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.
The generated Markdown also adds a backlink to the root site index:
```txt
---
Site index: [llms.txt](https://example.com/llms.txt)
```
When a generated Markdown page links to another known page on the same site, OpenNav rewrites that link to the other page’s `.md` endpoint. For example, a link from `/docs/guide/` to `/docs/api/` becomes a link to `https://example.com/docs/api.md` when OpenNav has a matching Markdown artifact for that page.
External links and links to unknown pages are left alone.
See the [content extraction reference](https://docs.opennav.ai/reference/content-extraction/index.md) for the exact `stripLayout` behavior.
## HTML Resource Links
[Section titled “HTML Resource Links”](#html-resource-links)
OpenNav also updates supported HTML pages with safe `` resource links. These links let agents discover the Markdown mirror and root `llms.txt` from the HTML page they already reached:
```txt
```
OpenNav marks the links it manages so future runs can replace stale OpenNav links without disturbing other `` content.
## Platform Headers
[Section titled “Platform Headers”](#platform-headers)
OpenNav can also write platform-specific static header files when the caller configures a supported platform. Today the supported platform is [Cloudflare Pages](https://docs.opennav.ai/platforms/cloudflare/index.md).
For Cloudflare Pages, `platform: "cloudflare-pages"` or `--platform cloudflare-pages` creates or updates `_headers` by default. The managed block sets concrete content types for generated artifacts:
.md
```txt
Content-Type: text/markdown; charset=utf-8
/llms.txt Content-Type: text/plain; charset=utf-8
/.well-known/opennav.json Content-Type: application/json; charset=utf-8
```
The same `_headers` block also adds HTTP `Link` headers for each HTML route. Those headers point agents at the generated Markdown mirror for that page and the root `llms.txt` index:
```txt
/docs/page Link: ; rel="alternate"; type="text/markdown" Link: ; rel="index"; type="text/plain"
```
OpenNav only owns the block between `# Begin OpenNav AI` and `# End OpenNav AI`. Existing Cloudflare `_headers` rules outside that block are preserved. If an existing route rule overlaps with an OpenNav route, OpenNav reports a warning instead of rewriting `_headers`.
## `llms.txt` And `llms-full.txt`
[Section titled “llms.txt And llms-full.txt”](#llmstxt-and-llms-fulltxt)
`llms.txt` is the compact entrypoint. It groups known pages by route and links agents to the generated `.md` endpoints.
`llms-full.txt` is the expanded readable bundle. OpenNav adds pages as complete blocks while the file stays within the configured token limit. When adding the next page would exceed that limit, OpenNav stops before that page and returns a `LLMS_FULL_TXT_TOKEN_LIMIT_REACHED` warning with the omitted page paths. It does not truncate a page body mid-block.
## `opennav.json`
[Section titled “opennav.json”](#opennavjson)
OpenNav publishes `.well-known/opennav.json` so tools can verify what this build supports without guessing from filenames.
The manifest records the static compatibility profile, generated artifact paths, resource-link support, Content Signals support, and a build fingerprint. Today that helps OpenNav safely update its own files across builds. Over time, the manifest is intended to support broader OpenNav compatibility checks as the static profile becomes part of a wider agent-navigation standard.
## `robots.txt`
[Section titled “robots.txt”](#robotstxt)
OpenNav only creates or edits `robots.txt` for Content Signals when `accessGuidance` is configured.
When enabled, OpenNav writes a managed block between `# Begin OpenNav AI` and `# End OpenNav AI`. Existing unmanaged `robots.txt` rules are preserved. If OpenNav sees unmanaged Content Signals it cannot safely reconcile, it reports a warning instead of rewriting that file.
## Files OpenNav Skips
[Section titled “Files OpenNav Skips”](#files-opennav-skips)
OpenNav skips files that are not useful as readable page content or that should not be treated as page routes.
Skipped files include JavaScript, CSS, source maps, images, fonts, media, archives, framework payload files, platform routing files, and static HTTP error pages such as `404.html` and `500.html`.
Skipped paths are reported in `skippedFilePaths`, with warnings when the skip is important for a user to see.
## What OpenNav Does Not Do
[Section titled “What OpenNav Does Not Do”](#what-opennav-does-not-do)
OpenNav does not edit your source project. It only reads and writes the configured static output folder.
OpenNav does not publish or deploy the site. Your existing hosting workflow still deploys the finished folder.
OpenNav does not enforce crawler behavior. Content Signals express preferences in `robots.txt`; use crawler controls, WAF rules, bot management, authentication, or paywalling when you need enforcement.
[PreviousOverview](https://docs.opennav.ai/index.md)
[NextGetting Started](https://docs.opennav.ai/getting-started/index.md)
---
Site index: [llms.txt](https://docs.opennav.ai/llms.txt)