---
title: Search
description: Understand how docs.page indexes your MDX and surfaces results in the Cmd+K command palette.
---
Readers expect to jump to any page in seconds. On a hosted docs.page site, they do that from a single search bar, with no third-party widget, API key, or extra configuration in `docs.json`.
## Overview
On-site search is built into every **published** docs.page site. When someone opens your docs, the browser loads a search index derived from the same MDX files GitHub serves for page rendering. Queries run locally in the reader's browser, so keystrokes stay responsive even on large doc sets.
Search is separate from **search engine indexing** (sitemap, `robots.txt`, and SEO metadata). On-site search helps readers who are already on your docs; SEO settings help Google and other crawlers find your site. See [SEO](/customize/seo) for crawler-facing configuration.
Local preview does not include search. Use a [branch preview](/features/branch-preview) URL or your production site to try it.
## How it works
### Index from your repository
When a reader opens search, the UI fetches `search.json` for the current site and ref. docs.page builds that payload on the server by listing MDX files under `docs/` in your GitHub repository, fetching their contents, and extracting searchable text.
Each indexed document includes:
- **path:** the URL path readers navigate to
- **title:** from page frontmatter or the first heading in the file
- **content:** plain text stripped from the MDX body (components and markup removed)
Pages with empty bodies are omitted. The index reflects the same ref as the page the reader is viewing: default branch for production URLs, or a branch, commit, or pull request when the URL includes a `~ref` segment.
```
https://docs.page/{owner}/{repo}/search.json
https://docs.page/{owner}/{repo}~{ref}/search.json
```
On custom domains and vanity subdomains, the path follows the same routing rules as doc pages; only the host changes.
The JSON response includes a `documents` array and a `meta` object with the resolved ref, commit SHA, file count, and whether the repository tree was truncated. See [HTTP endpoints: search.json](/reference/http-endpoints#searchjson) for the response shape.
### Client-side full-text search
After `search.json` loads, a Web Worker builds a [FlexSearch](https://github.com/nextapps-de/flexsearch) index in the browser. Title and body text are indexed separately with forward tokenization and normalized matching.
When the reader types a query:
1. The worker searches the in-memory index
2. Matching documents return with highlighted title and snippet HTML
3. Selecting a result navigates to that page path
Search runs entirely in the browser after the initial fetch. The query string is not sent to a separate search API on each keystroke.
### Command palette (⌘K)
Search lives in a command palette opened from the header **Search** button or **⌘K** (Ctrl+K on Windows and Linux). The palette is more than a search box. It also surfaces quick navigation when the input is empty:
- **Navigate:** jump to configured [navigation tabs](/features/tabs)
- **Ask AI:** open the in-docs agent panel when [Ask AI](/ai-agents/ask-ai) is enabled
- **Install MCP:** open the **Install MCP** dialog when MCP is enabled (`mcp.enabled` is not `false`)
- **GitHub:** open the source repository
The same MCP and Ask AI shortcuts appear in the **page action menu** (**Copy page** chevron): **Install with MCP**, **Connect to Cursor**, **Connect to VSCode**, plus **Open in Claude** for external Claude web chat. See [Page actions](/features/public-github-hosting#page-actions) and [MCP server](/ai-agents/mcp-server#connect-from-the-live-site).
Type to search page titles and body text. Results show the page title, path, and a short snippet from the matching content.
**Title-only mode:** Prefix your query with `>` to search page titles only. A **Search pages** badge appears while title-only mode is active. Press **Backspace** on an empty query to return to full-text search.
Short queries return up to five results; longer queries return up to ten. Results deduplicate paths that differ only by trailing slashes or `/index` suffixes.
## Related
Response shape, indexed fields, and metadata for `search.json`.
Sitemap, robots.txt, and crawler-facing SEO settings.
Preview search on a branch or pull request before merge.
Page action menu: Copy page, View markdown, and MCP shortcuts.