Moss - Real-time Semantic Search for Conversational AI

Add semantic search to your VitePress documentation site using the vitepress-plugin-moss package. The plugin automatically indexes your content at build time and replaces the default search with a fast, semantic search interface powered by Moss.

Note: For the full plugin source and a demo site, see the vitepress-plugin-moss package.

Why use Moss with VitePress?

VitePress’s built-in search relies on keyword matching, which misses results when users phrase queries differently than the docs. Moss semantic search understands meaning, so users find what they need even when their wording doesn’t match the docs exactly. Queries run in under 10ms once the local index loads.

Required tools

Moss account with project credentials
VitePress 1.0+
Node.js 18+

Integration guide

Installation

npm
pnpm
yarn

npm install vitepress-plugin-moss

pnpm add vitepress-plugin-moss

yarn add vitepress-plugin-moss

Your project’s package.json must have "type": "module" because VitePress is ESM-only.

Environment setup

Create a .env file in your project root (add it to .gitignore).

.env

MOSS_PROJECT_ID=your_project_id
MOSS_PROJECT_KEY=your_api_key
MOSS_INDEX_NAME=my-docs

Configure VitePress

Add the Moss plugin and search options to your VitePress config.

docs/.vitepress/config.ts

import { defineConfig } from 'vitepress'
import { mossIndexerPlugin } from 'vitepress-plugin-moss'

export default defineConfig({
  title: 'My Docs',
  themeConfig: {
    search: {
      provider: 'moss' as any,
      options: {
        projectId: process.env.MOSS_PROJECT_ID!,
        projectKey: process.env.MOSS_PROJECT_KEY!,
        indexName: process.env.MOSS_INDEX_NAME!,
      },
    },
  },
  vite: {
    plugins: [mossIndexerPlugin()],
  },
})

Build and test

When you run vitepress build, the plugin automatically parses your Markdown, chunks it into semantic segments, and uploads them to Moss. For local development, start the dev server and press Ctrl+K or Cmd+K to test search.

vitepress dev docs

How it works

The plugin uses a two-phase search architecture:

Cloud hot-path — From the first keystroke, queries route to Moss cloud for instant results.
Local WebAssembly — In the background, the local model and index download in parallel. Once ready, queries switch to sub-10ms on-device search automatically.

Excluding pages

Add search: false to a page’s frontmatter to exclude it from the index.

---
search: false
---

Configuration

Search options

All options go under themeConfig.search.options in your VitePress config.

Parameter	Type	Default	Description
`projectId`	`string`	Required	Your Moss Project ID.
`projectKey`	`string`	Required	Your Moss Project Key.
`indexName`	`string`	Required	Name of the index to create on every build.
`topK`	`number`	`10`	Number of results to return.
`placeholder`	`string`	`"Search docs..."`	Search input placeholder text.
`buttonText`	`string`	`"Search"`	Nav bar search button label.

Keyboard shortcuts

Key	Action
`Ctrl+K` / `Cmd+K`	Open or close search
`/`	Open search (when not focused on an input)
`Up` / `Down`	Navigate results
`Enter`	Go to selected result
`Esc`	Close search

Voice & Real-time

AI Frameworks

Developer Tools

VitePress

Why use Moss with VitePress?

Required tools

Integration guide

How it works

Excluding pages

Configuration

Search options

Keyboard shortcuts

​Why use Moss with VitePress?

​Required tools

​Integration guide

​How it works

​Excluding pages

​Configuration

​Search options

​Keyboard shortcuts

Why use Moss with VitePress?

Required tools

Integration guide

How it works

Excluding pages

Configuration

Search options

Keyboard shortcuts