docs(plugin-slimsearch): improve docs

docs/plugins/search/meilisearch.md

@@ -8,57 +8,86 @@ icon: https://www.meilisearch.com/favicon.ico
 
 Integrate [MeiliSearch](https://www.meilisearch.com/) into VuePress, which can provide search to your documentation site.
 
-## Usage
+## Setup MeiliSearch
 
-```bash
-npm i -D @vuepress/plugin-meilisearch@next
-```
+To use MeiliSearch for free, you need to self-host it on your own server, otherwise you need to pay for MeiliSearch Cloud.
 
-```ts
-import { MeiliSearchPlugin } from '@vuepress/plugin-meilisearch'
+::: info MeiliSearch Cloud
 
-export default {
-  plugins: [
-    meilisearchPlugin({
-      // Configuration options
-      host: '',
-      apiKey: '',
-      indexUid: '',
-    }),
-  ],
-}
-```
+To use MeiliSearch Cloud, you need to create an account and set up a new instance. You can find the instructions in the [MeiliSearch Cloud documentation](https://www.meilisearch.com/docs/cloud/getting_started).
+
+:::
+
+### Starting MeiliSearch
 
-## Self-hosting MeiliSearch
+::: tip
 
-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.
+In this section, we use Docker to self-host Meilisearch, see [MeiliSearch Docker docs](https://www.meilisearch.com/docs/guides/misc/docker) for details.
+
+If you don't have Docker installed, you may also [install MeiliSearch manually](https://www.meilisearch.com/docs/learn/self_hosted/getting_started_with_self_hosted_meilisearch#setup-and-installation).
+
+:::
+
+First pull latest MeiliSearch docker image:
 
 ```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.
+Then start the docker:
 
-```sh
+```sh :no-line-numbers
 docker run -it --rm \
+  # set container name to "MeiliSearch"
+  --name MeiliSearch \
+  # set your own master key
+  # replace <YOUR_MASTER_KEY> with your own master key
+  -e MEILI_MASTER_KEY='<YOUR_MASTER_KEY>' \
+  # switch to production mode
+  -e MEILI_ENV=production \
+  # disable meilisearch analytics
+  -e MEILI_NO_ANALYTICS=1 \
+  # mapping 7700 port to host
   -p 7700:7700 \
+  # mounting index database to host
+  # you can change the path to anywhere you want
   -v $(pwd)/meili_data:/meili_data \
   getmeili/meilisearch:latest
 ```
 
-> See <https://www.meilisearch.com/docs/guides/misc/docker>
+Here `<YOUR_MASTER_KEY>` is the master key for MeiliSearch that you should set yourself (required >= 16 bytes), which is used to access the MeiliSearch API.
 
-## Crawling the website
+::: important Never expose Master Key
 
-MeiliSearch provides a Docker crawler to crawl documents. Until then, make sure MeiliSearch is running.
+Search key can be generated for public access, which only allows search operations.
 
-Here is a sample of crawler configuration, which you should save, modify and pass to the crawler:
+Your Master Key should only be used for internal server access (including scraping), as it grants full operational permissions. Do not mix use them and **never expose this key**!
 
-```json
+:::
+
+### Setting up the Scraper
+
+::: tip
+
+MeiliSearch provides a Docker Scraper image to scrape your documents. for details, see [MeiliSearch: scrape your content](https://www.meilisearch.com/docs/guides/front_end/search_bar_for_docs#scrape-your-content).
+
+If you don't have Docker installed, you can [run scraper from source code](https://github.com/meilisearch/docs-scraper?tab=readme-ov-file#from-source-code-).
+
+:::
+
+First, pull the latest MeiliSearch Scraper image:
+
+```sh
+docker pull getmeili/docs-scraper:latest
+```
+
+Then, create a **correct configuration file** for the scraper. Here, we provide a sample, which you should save it locally and modify according to your needs:
+
+```json :collapsed-lines=10
 {
-  "index_uid": "YOUR_INDEX_NAME",
-  "start_urls": ["https://YOUR_WEBSITE_URL/"],
-  "sitemap_urls": ["https://YOUR_WEBSITE_URL/sitemap.xml"],
+  "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",
@@ -125,11 +154,12 @@ Here is a sample of crawler configuration, which you should save, modify and pas
 }
 ```
 
-- `start_urls` and `sitemap_urls` (optional) shall be customized according to the website to be crawled.
+- `index_uid` should be a unique name for your index, which will be used to search.
+- `start_urls` and `sitemap_urls` (optional) shall be customized according to the website to be scraped.
 - `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
+::: important Requirements for the configuration file
 
 To let the plugin work:
 
@@ -138,64 +168,141 @@ To let the plugin work:
 
 :::
 
-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:
+Make sure MeiliSearch is currently running, then start scraping the document by running the docker:
 
 ```sh
 docker run -t --rm \
   --network=host \
   -e MEILISEARCH_HOST_URL='<MEILISEARCH_HOST_URL>' \
-  -e MEILISEARCH_API_KEY='<MASTER_KEY>' \
+  -e MEILISEARCH_API_KEY='<MEILISEARCH_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.
+Here:
+
+- `<MEILISEARCH_HOST_URL>` should be the host URL of your MeiliSearch instance
+- `<MEILISEARCH_MASTER_KEY>` shall be the master key you provided.
+- `<absolute-path-to-your-config-file>` is the absolute path to the configuration file you created above.
 
-> See <https://www.meilisearch.com/docs/guides/front_end/search_bar_for_docs#scrape-your-content>
+When the scraper completes, MeiliSearch will update the existing index with latest document content.
 
-## Get search index and api key
+### Setting up the Plugin
 
-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.
+A search-only access key shall be generated for the plugin to work. This key can be generated using the MeiliSearch API.
+You can use the following command to create a search-only access key:
 
 ```sh
 curl \
-  -X POST 'http://localhost:7700/keys' \
+  # Replace <YOUR_HOST> with your MeiliSearch host URL
+  -X POST '<YOUR_HOST>/keys' \
   -H 'Content-Type: application/json' \
   -H 'Authorization: Bearer <MASTER_KEY>' \
+  # description f
   --data-binary '{
-    "description": "Search records key",
+    "indexes": ["<YOUR_INDEX_NAME>"]，
     "actions": ["search"],
-    "indexes": ["YOUR_INDEX_NAME"],
-    "expiresAt": "2025-01-01T00:00:00Z"
+    "expiresAt": null,
+    "description": "Search key for <YOUR_INDEX_NAME>"
   }'
 ```
 
+Here:
+
+- `<YOUR_HOST>` is the host URL of your MeiliSearch instance
+- `<MASTER_KEY>` is the master key generated by MeiliSearch
+- `<YOUR_INDEX_NAME>` is the name of the index you created
+- `actions` specifies the actions that this key can perform. In this case, it is set to `["search"]`, which means it can only perform search operations.
+- `expiresAt` sets the expiration date for the key, allowing you to control how long the key remains valid, `null` means it will never expire.
+
 If successful, the response would look like this:
 
 ```json
 {
   "name": null,
-  "description": "Search records key",
+  "description": "Search key for <YOUR_INDEX_NAME>",
   "key": "adaf72e2a6d6f428ec465bc786ec41de868bbd53121997e89ba2299e9566c88213",
   "uid": "b84d1be5-caa5-4752-b078-8f40be39051d",
   "actions": ["search"],
-  "indexes": ["YOUR_INDEX_NAME"],
-  "expiresAt": "2025-01-01T00:00:00Z",
+  "indexes": ["<YOUR_INDEX_NAME>"],
+  "expiresAt": null,
   "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.
+Now, you can use the `key` in the plugin configuration. Install the plugin in your VuePress project and then provide required options:
+
+```bash
+npm i -D @vuepress/plugin-meilisearch@next
+```
 
 ```ts
-meilisearchPlugin({
-  host: 'YOUR_HOST',
-  apiKey: 'adaf72e2a6d6f428ec465bc786ec41de868bbd53121997e89ba2299e9566c88213',
-  indexUid: 'YOUR_INDEX_NAME',
-})
+import { meiliSearchPlugin } from '@vuepress/plugin-meilisearch'
+
+export default {
+  plugins: [
+    meilisearchPlugin({
+      host: '<MEILISEARCH_HOST_URL>',
+      apiKey: '<YOUR_SEARCH_ONLY_KEY>',
+      indexUid: '<YOUR_INDEX_NAME>',
+    }),
+  ],
+}
 ```
 
+### Automatic Re-scraping with Github Actions
+
+Place your scraper config file somewhere in your project.
+
+Then go to `Settings` -> `Secrets and variables` -> `Actions` in your Github repository. Click `New repository secret` and set `MEILISEARCH_MASTER_KEY` with your meilisearch master key.
+
+Next add a new step `scrape` in your Github Actions workflow file, which will run after the deployment step. Here is an example of how to do this:
+
+```yml
+name: Deploy and Scrape
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      # deploy your documentation here
+      # ...
+
+  scrape:
+    needs: deploy
+    runs-on: ubuntu-latest
+    name: re-scrape documentation for Meilisearch
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Run scraper
+        env:
+          # replace with your own MeiliSearch host URL
+          HOST_URL: <YOUR_MEILISEARCH_HOST_URL>
+          API_KEY: ${{ secrets.MEILISEARCH_MASTER_KEY }}
+          # replace it with the path to your config file
+          CONFIG_FILE_PATH: ${{ github.workspace }}/<path/to/your/scraper/config.json>
+        run: |
+          docker run -t --rm \
+            -e MEILISEARCH_HOST_URL=$HOST_URL \
+            -e MEILISEARCH_API_KEY=$API_KEY \
+            -v $CONFIG_FILE_PATH:/docs-scraper/config.json \
+            getmeili/docs-scraper:latest pipenv run ./docs_scraper config.json
+```
+
+::: tip Key for Scraper
+
+To secure your MeiliSearch instance, you can create a new key with limited permissions for the scraper. Similar to search key above, this key should only have access to these actions: `["indexes.create","indexes.delete","settings.update","documents.add"]`
+
+:::
+
 ## Options
 
 ### host