Search and AI

Search#

Every Shiso site ships with client-side search — no service or API key required. Open it with the header button or ⌘K / Ctrl K.

The index is built at compile time from your content: each page is split into heading-bounded sections, so results land on the exact section that matched. Pages marked hidden in navigation stay out of the index.

Customize the input placeholder and shortcut with search.prompt, search.shortcut, and search.shortcutLabel. Set shortcut to false to disable only the shortcut, or set search to false to remove search:

{
  "search": {
    "prompt": "Search the docs...",
    "shortcut": "k",
    "shortcutLabel": "Ctrl K"
  }
}

Search position#

By default the search control sits on the right side of the header. Move it with search.position:

• header (default) — right side of the header.
• sidebar — top of the navigation column. On small screens, where the sidebar collapses into a menu, it stays in the header.

{
  "search": {
    "position": "sidebar"
  }
}

Positions are named slots rather than layout coordinates, so themes decide how each one looks. Every theme supports header; if a theme doesn't implement the position you asked for, search falls back to the header.

To hide the search control and disable its shortcut on one page, set search: false in that page's frontmatter:

---
title: Welcome
search: false
---

Search providers#

The built-in local provider is used by default. Shiso also ships a built-in Pagefind provider, and you can register your own. Select a provider with search.provider; options are passed directly to its factory:

{
  "search": {
    "prompt": "Search the docs...",
    "provider": "hosted",
    "options": { "index": "docs" }
  }
}

Pagefind#

Pagefind indexes the prerendered HTML during shiso build, giving better relevance ranking, stemming, and multi-language support than the local index — still fully static, with no service required.

Install the pagefind package (an optional dependency of @umami/shiso) and select the provider:

pnpm add -D pagefind

{
  "search": {
    "provider": "pagefind"
  }
}

shiso build then writes the search bundle to dist/client/pagefind/. In shiso dev there is no prerendered HTML to index, so search transparently falls back to the local provider until you build.

Supported options:

• ranking: passed to Pagefind's runtime ranking options, e.g. { "termFrequency": 0.8 }
• excludeSelectors: CSS selectors to exclude from indexing, e.g. [".changelog-date"] (heading permalink anchors are always excluded)

Hidden pages and scopes are excluded from the index, and on multi-version or multi-language sites results stay inside the version and language being browsed, matching the local provider's behavior.

Custom providers#

Register custom providers in entry-client.tsx before hydrating Shiso:

import { ShisoApp } from '@umami/shiso/client';
import { hydrateRoot } from 'react-dom/client';
import { registerSearchProvider } from '@umami/shiso/search';

registerSearchProvider('hosted', options => ({
  async search(query, limit = 10) {
    const params = new URLSearchParams({ q: query, limit: String(limit) });
    const response = await fetch('/api/search?' + params);

    return response.json();
  },
}));

const element = document.getElementById('root');

if (!element) {
  throw new Error('Shiso could not find the root element.');
}

hydrateRoot(element, <ShisoApp />);

Every provider returns normalized results with url, page, score, and optional heading and snippet fields. Snippets may wrap matched terms in <mark> tags, which the search dialog renders as highlights (snippets are parsed, never injected as HTML). Provider options are included in the browser bundle, so do not put private API keys in them. An unknown provider id logs a warning and falls back to local.

Markdown export#

The production build publishes the raw markdown of every page next to its HTML:

/docs/installation      the rendered page
/docs/installation.md   the markdown source

This powers the contextual menu below and gives AI tools a clean, token-efficient version of every page.

AI discovery files#

Every production build also writes two site-level discovery files:

• /llms.txt lists navigable pages in documentation order with their titles, descriptions, and Markdown URLs.
• /llms-full.txt combines that public Markdown corpus into one file.

Pages marked noindex, and hidden pages or scopes under the default navigable indexing policy, are omitted. Set seo.indexing to all to include hidden documentation pages.

Contextual menu#

The contextual key adds a menu beside the page title for AI-optimized actions. The first option is the primary button; the rest go in a dropdown.

{
  "contextual": {
    "options": ["copy", "view", "chatgpt", "claude", "perplexity"]
  }
}

• copy: copy the page as Markdown to the clipboard
• view: open the page's markdown source in a new tab
• chatgpt, claude, perplexity: open the assistant with a prompt pointing at the page's markdown URL (requires siteUrl in shiso.config.ts)

Custom options#

Define your own entries as objects. $path expands to the page path and $page to the page's markdown URL:

{
  "contextual": {
    "options": [
      "copy",
      {
        "title": "Ask support",
        "description": "Send this page to the support bot",
        "icon": "life-buoy",
        "href": "https://example.com/ask?page=$path",
        "target": "_blank"
      }
    ]
  }
}

Custom options render the configured icon and infer _self for local links and _blank for external links unless target overrides it.