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.
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 for crawler-facing configuration.
Local preview does not include search. Use a branch preview URL or your production site to try it.
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.jsonOn 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 for the response shape.
After search.json loads, a Web Worker builds a FlexSearch index in the browser. Title and body text are indexed separately with forward tokenization and normalized matching.
When the reader types a query:
- The worker searches the in-memory index
- Matching documents return with highlighted title and snippet HTML
- 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.
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
- Ask AI: open the in-docs agent panel when Ask AI is enabled
- Install MCP: open the Install MCP dialog when MCP is enabled (
mcp.enabledis notfalse) - 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 and MCP server.
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.