feat(plugin-meilisearch): support meilisearch

.vscode/settings.json

@@ -52,6 +52,7 @@
     "mathjax",
     "mdast",
     "mdit",
+    "meilisearch",
     "meteorlxy",
     "mhchem",
     "nord",

docs/.vuepress/configs/sidebar/en.ts

@@ -141,7 +141,13 @@ export const sidebarEn: SidebarOptions = {
     'register-components',
   ],
 
-  '/plugins/search/': ['guidelines', 'docsearch', 'search', 'slimsearch'],
+  '/plugins/search/': [
+    'guidelines',
+    'docsearch',
+    'meilisearch',
+    'search',
+    'slimsearch',
+  ],
 
   '/plugins/seo/': [
     {

docs/.vuepress/configs/sidebar/zh.ts

@@ -141,7 +141,13 @@ export const sidebarZh: SidebarOptions = {
     'register-components',
   ],
 
-  '/zh/plugins/search/': ['guidelines', 'docsearch', 'search', 'slimsearch'],
+  '/zh/plugins/search/': [
+    'guidelines',
+    'docsearch',
+    'meilisearch',
+    'search',
+    'slimsearch',
+  ],
 
   '/zh/plugins/seo/': [
     {

docs/plugins/search/meilisearch.md

@@ -0,0 +1,274 @@
+---
+icon: https://www.meilisearch.com/favicon.ico
+---
+
+# meilisearch
+
+<NpmBadge package="@vuepress/plugin-meilisearch" />
+
+Integrate [MeiliSearch](https://www.meilisearch.com/) into VuePress, which can provide search to your documentation site.
+
+## Usage
+
+```bash
+npm i -D @vuepress/plugin-meilisearch@next
+```
+
+```ts
+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.
+
+```sh
+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.
+
+```sh
+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:
+
+```json
+{
+  "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.
+
+::: important
+
+To let the plugin work:
+
+- `lang` selector must be kept as is in `selectors` filed
+- All fields that are currently in `custom_settings` must not be removed.
+
+:::
+
+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:
+
+```sh
+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.
+
+```sh
+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:
+
+```json
+{
+  "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.
+
+```ts
+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](https://www.meilisearch.com/docs/reference/api/search#search-parameters)
+
+## Components
+
+- SearchBox