Search
Search your docs in the browser out of the box, or with Algolia or Orama Cloud.
Your site has search without any setup: press Ctrl K, or ⌘ K on macOS, or click the search button of the layout.
Built-in Search
At build time, Vuesho writes a search index for each language to /_vuesho/search/<lang>.json. It holds the title, description, headings and text of every page. The browser loads the index on the first search and searches it itself, so search works on a static host, with no server or search service.
A text matches when it contains every word of the query, ignoring case. Pages are ranked by where they match: a match in the title counts most, then a match in the description, then each matching heading, then each matching paragraph. The dialog shows the 10 best pages, each with up to 4 of its matching headings and paragraphs. On a site with languages, the dialog searches the index of the page's language.
With a dynamic source, the server builds the index on request instead.
Leaving Pages Out
filter of the search plugin leaves out the pages it returns false for, like the pages under /changelog:
import { createSite, recommendedPreset } from "vuesho/config";
import { defineDocs } from "vuesho/content";
const docs = defineDocs();
export default createSite(docs.toFumadocsSource()).config({
preset: recommendedPreset({
search: { filter: (page) => !page.url.startsWith("/changelog") },
}),
});Dialog Options
The search plugin also takes the options of the dialog:
links: the links it shows before a query, as[name, href].hotKey: the keys that open it, pressed together, each with how it shows. It defaults to ⌘ or Ctrl, and K.preload:falseloads the code of the dialog on the first search, in place of once the page is idle.
export default createSite(docs.toFumadocsSource()).config({
preset: recommendedPreset({
search: {
links: [["Getting Started", "/guide"]],
hotKey: [{ key: "/", display: "/" }],
},
}),
});Turning It Off
Search is a default plugin. Leave it out with recommendedPreset(), and the search button disappears:
import { createSite, recommendedPreset } from "vuesho/config";
import { defineDocs } from "vuesho/content";
const docs = defineDocs();
export default createSite(docs.toFumadocsSource()).config({
preset: recommendedPreset({ search: false }),
});Using Algolia or Orama Cloud
For a hosted search service, give the site a search dialog of your own. The UI has dialogs for Algolia and Orama Cloud, which search an index you fill yourself: Vuesho doesn't sync your pages to the service.
Turn Off the Built-in Index
Set index: false on the search plugin, so your site keeps its search and no longer builds its own index:
export default createSite(docs.toFumadocsSource()).config({
preset: recommendedPreset({ search: { index: false } }),
});Wrap the Dialog
Install the client of your service, then write a component that renders its dialog with your client. A search dialog receives the open prop and emits update:open.
npm install algoliasearch<script setup lang="ts">
import { liteClient } from "algoliasearch/lite";
import AlgoliaSearchDialog from "vuesho/ui/components/dialog/search-algolia";
defineProps<{ open: boolean }>();
const emit = defineEmits<{ "update:open": [open: boolean] }>();
const client = liteClient("YOUR_APP_ID", "YOUR_SEARCH_API_KEY");
</script>
<template>
<AlgoliaSearchDialog
:open="open"
:search-options="{ client, indexName: 'docs' }"
@update:open="emit('update:open', $event)"
/>
</template>Set show-algolia to show the "Powered by Algolia" label.
Both dialogs take tags and defaultTag to filter results by tag.
Put the Dialog in the Slot
Give your dialog to the slot search-dialog of your theme. It replaces the dialog of the default theme:
import { defineAsyncComponent } from "vue";
import { defineTheme } from "vuesho/theme";
import defaultTheme from "vuesho/theme/default";
export default defineTheme({
extends: defaultTheme,
slots: { "search-dialog": defineAsyncComponent(() => import("./SearchDialog.vue")) },
});The search button and the shortcut now open your dialog. With defineAsyncComponent(), its code loads once the page is idle, or on the first search with preload: false.