meilisearch

Integrate MeiliSearch into VuePress, which can provide search to your documentation site.

Usage

npm i -D @vuepress/plugin-meilisearch@next

import { MeiliSearchPlugin } from '@vuepress/plugin-meilisearch'

export default {
  plugins: [
    meilisearchPlugin({
      // Configuration options
      host: '',
      apiKey: '',
      indexUid: '',
    }),
  ],
}

Self-hosting MeiliSearch

MeiliSearch provides a server program that supports self-deployment options for users with cloud servers. To simplify the process of running MeiliSearch on the server side, you can use Docker for installation and management.

docker pull getmeili/meilisearch:latest

On the first startup, a Master Key will be generated by default. Do not expose this key; it should only be used for internal server access, as it grants full operational permissions.

docker run -it --rm \
  -p 7700:7700 \
  -v $(pwd)/meili_data:/meili_data \
  getmeili/meilisearch:latest

See https://www.meilisearch.com/docs/guides/misc/docker

Crawling the website

MeiliSearch provides a Docker crawler to crawl documents. Until then, make sure MeiliSearch is running.

Here is a sample of crawler configuration, which you should save, modify and pass to the crawler:

{
  "index_uid": "YOUR_INDEX_NAME",
  "start_urls": ["https://YOUR_WEBSITE_URL/"],
  "sitemap_urls": ["https://YOUR_WEBSITE_URL/sitemap.xml"],
  "selectors": {
    "lvl0": {
      "selector": ".vp-sidebar-heading.active",
      "global": true,
      "default_value": "Documentation"
    },
    "lvl1": "[vp-content] h1",
    "lvl2": "[vp-content] h2",
    "lvl3": "[vp-content] h3",
    "lvl4": "[vp-content] h4",
    "lvl5": "[vp-content] h5",
    "lvl6": "[vp-content] h6",
    "content": "[vp-content] p, [vp-content] li",
    "lang": {
      "selector": "/html/@lang",
      "global": true,
      "type": "xpath"
    }
  },
  "custom_settings": {
    "searchableAttributes": [
      "hierarchy_radio_lvl0",
      "hierarchy_radio_lvl1",
      "hierarchy_radio_lvl2",
      "hierarchy_radio_lvl3",
      "hierarchy_radio_lvl4",
      "hierarchy_radio_lvl5",
      "hierarchy_lvl0",
      "hierarchy_lvl1",
      "hierarchy_lvl2",
      "hierarchy_lvl3",
      "hierarchy_lvl4",
      "hierarchy_lvl5",
      "hierarchy_lvl6",
      "content",
      "lang",
      "objectID",
      "page_rank",
      "level",
      "position"
    ],
    "displayedAttributes": [
      "hierarchy_radio_lvl0",
      "hierarchy_radio_lvl1",
      "hierarchy_radio_lvl2",
      "hierarchy_radio_lvl3",
      "hierarchy_radio_lvl4",
      "hierarchy_radio_lvl5",
      "hierarchy_lvl0",
      "hierarchy_lvl1",
      "hierarchy_lvl2",
      "hierarchy_lvl3",
      "hierarchy_lvl4",
      "hierarchy_lvl5",
      "hierarchy_lvl6",
      "anchor",
      "url",
      "lang",
      "content",
      "objectID"
    ],
    "filterableAttributes": ["lang"]
  }
}

• start_urls and sitemap_urls (optional) shall be customized according to the website to be crawled.
• selectors field can be customized according to third-party theme DOM structure.
• You can add new fields to custom_settings according to your needs.

Start scraping the document, MEILISEARCH_HOST_URL is the address of the host running MeiliSearch, <MASTER_KEY> is the master key, <absolute-path-to-your-config-file> is the absolute path to fetch the configuration file:

docker run -t --rm \
  --network=host \
  -e MEILISEARCH_HOST_URL='<MEILISEARCH_HOST_URL>' \
  -e MEILISEARCH_API_KEY='<MASTER_KEY>' \
  -v <absolute-path-to-your-config-file>:/docs-scraper/config.json \
  getmeili/docs-scraper:latest pipenv run ./docs_scraper config.json

When the crawl is complete, MeiliSearch stores the crawled document in the specified index.

See https://www.meilisearch.com/docs/guides/front_end/search_bar_for_docs#scrape-your-content

Get search index and api key

To create an access key that only allows search operations, use the following request. The indexes array specifies which indexes this key can access, and expiresAt sets the key's expiration date.

curl \
  -X POST 'http://localhost:7700/keys' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <MASTER_KEY>' \
  --data-binary '{
    "description": "Search records key",
    "actions": ["search"],
    "indexes": ["YOUR_INDEX_NAME"],
    "expiresAt": "2025-01-01T00:00:00Z"
  }'

If successful, the response would look like this:

{
  "name": null,
  "description": "Search records key",
  "key": "adaf72e2a6d6f428ec465bc786ec41de868bbd53121997e89ba2299e9566c88213",
  "uid": "b84d1be5-caa5-4752-b078-8f40be39051d",
  "actions": ["search"],
  "indexes": ["YOUR_INDEX_NAME"],
  "expiresAt": "2025-01-01T00:00:00Z",
  "createdAt": "2024-01-27T06:50:33.668329328Z",
  "updatedAt": "2024-01-27T06:50:33.668329328Z"
}

This key can be exposed and used externally as needed. Enter it in your plugin options.

meilisearchPlugin({
  host: 'YOUR_HOST',
  apiKey: 'adaf72e2a6d6f428ec465bc786ec41de868bbd53121997e89ba2299e9566c88213',
  indexUid: 'YOUR_INDEX_NAME',
})

Options

host

• Type: string

• Required: true

• Details:

  Provide the HTTP address of the MeiliSearch API.

apiKey

• Type: string

• Required: true

• Details:

  API key generated by MeiliSearch.

indexUid

• Type: string

• Required: true

• Details:

  Specify the index name used for searching.

translations

• Type: DocSearchTranslations

• Details:

  Allows you to replace the default text in the DocSearch button and popup.

hotKeys

• Type: string[] | false

• Default: ['ctrl+k', 's', '/']

• Details:

  An array of hotkeys to trigger the search modal. When the value is false, the search modal cannot be triggered with any key.

debounceDuration

• Type: number | false

• Default: 200

• Details:

  The number of milliseconds that wait between keystrokes to determine whether a search should be performed，Setting the value here to 0 or false is logically equivalent.

searchParams

• Type: SearchParams

• Required: false

• Details:

  Parameters of MeiliSearch API.

• Also see:

  • Meilisearch API docs

Components

• SearchBox