Sitemap Configuration

The sitemap is a JSON structure that describes your application to the AI. It tells Navieo what routes exist and what interactive elements are on each page.

How the Sitemap Is Generated

When you click Scan Codebase in the Navieo dashboard, Navieo reads your source code via the GitHub API and automatically generates the sitemap. You don't need to write or maintain this file manually.

The scan produces a .navieo/sitemap.json file in your repository (via Pull Request) that looks like this:

{
  "appId": "my-app",
  "framework": "nextjs",
  "generatedAt": "2026-02-15T00:00:00Z",
  "routes": []
}

See GitHub Integration for the full scanning workflow.

Routes

Each route describes a page and the interactive elements on it:

{
  "routes": [
    {
      "path": "/dashboard",
      "title": "Dashboard",
      "description": "Main dashboard with project list and stats",
      "elements": [
        {
          "id": "create-project",
          "type": "button",
          "text": "Create Project",
          "selector": { "cssSelector": "#create-project" },
          "description": "Opens the new project creation dialog"
        },
        {
          "id": "nav-settings",
          "type": "link",
          "text": "Settings",
          "selector": { "cssSelector": "nav a[href='/settings']" },
          "description": "Navigation link to the settings page"
        }
      ]
    }
  ]
}

Element Types

Type	Description
`button`	Clickable button element
`link`	Navigation link (`<a>` tag)
`input`	Text input field
`select`	Dropdown select element
`text`	Informational text or section

Selector Strategies

Each element has a selector object with multiple strategies for finding it in the DOM. The SDK tries them in priority order and uses the first match:

{
  "selector": {
    "cssSelector": "#create-project",
    "navieoId": "create-project",
    "ariaLabel": "Create new project",
    "text": "Create Project"
  }
}

Field	Maps to	Runtime?	Notes
`cssSelector`	`document.querySelector(value)`	Yes	Any valid CSS selector
`navieoId`	`[data-navieo-id="value"]`	Yes	Maps to the HTML `data-navieo-id` attribute
`ariaLabel`	`[aria-label="value"]`	Yes	Maps to the HTML `aria-label` attribute
`text`	—	No	Metadata only — used by the AI for context, not for DOM lookup

Important: At least one of cssSelector, navieoId, or ariaLabel must be present for the SDK to find the element at runtime. The text field alone is not sufficient — it's metadata only.

Here are selector strategies ranked by reliability:

Strategy	Example	Stability
`id` attribute	`"#create-app-button"`	Best — unique, survives layout changes
`data-navieo-id`	`"button[data-navieo-id='save-btn']"`	Great — stable if you already use them for testing
Semantic selector	`"aside a[href='/docs']"`	Great — uses meaning, not position
`aria-label`	`"[aria-label='Create new project']"`	Good — accessible and stable
Structural selector	`"main > section:nth-of-type(2)"`	Fragile — breaks if layout changes
Class-based selector	`".bg-blue-600.text-white"`	Fragile — breaks with any styling change

Best practice: Add data-navieo-id or id attributes to key interactive elements in your app. The scanner auto-detects these and generates high-confidence selectors:

<button data-navieo-id="create-project" onClick={handleCreate}>
  Create Project
</button>

Route Visibility

Control which routes are included in the knowledge base and where the widget appears:

{
  "path": "/admin",
  "title": "Admin Panel",
  "description": "Internal admin panel",
  "elements": [],
  "visibility": {
    "indexed": false,
    "widgetVisible": false
  }
}

Field	Description
`indexed`	If `false`, route is excluded from the knowledge base
`widgetVisible`	If `false`, the chat widget is hidden on this route

You can also configure visibility from the Navieo dashboard.

Docs

Contextual documentation that helps the AI understand your application. Place markdown files in .navieo/docs/ in your repository:

.navieo/
  docs/
    getting-started.md
    billing.md
    team-management.md

These are synced automatically when you push to GitHub (if the GitHub integration is connected). You can also create and edit docs from the dashboard's Docs editor.

Tips

Add data-navieo-id to key elements — the scanner auto-detects these and gives them high-confidence selectors
Re-scan after major UI changes — click "Scan Codebase" in the dashboard to refresh your sitemap
Enrich with AI — click "Enrich with AI" after scanning for richer element descriptions
Build tours — create tours visually or with AI to give users guided walkthroughs
Include docs — contextual documentation helps the AI answer "why" questions, not just "how"