Merge pull request #924 from ExpressionEngine/feature/docsearch

Update doc search to use Meilisearch instead of Algolia

.github/workflows/build.yml

@@ -0,0 +1,45 @@
+name: Build Docs
+
+on:
+  push:
+    branches:
+      - 7.x
+      - 7.dev
+
+jobs:
+  build:
+    name: Build Documentation HTML
+    runs-on: ubuntu-latest
+    outputs:
+      DOCSEARCH_INDEX: ${{ steps.setup_vars.outputs.DOCSEARCH_INDEX }}
+      DOCS_URL: ${{ steps.setup_vars.outputs.DOCS_URL }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v2
+
+      - name: Setup Variables
+        id: setup_vars
+        run: |
+          if [[ "${{github.base_ref}}" == "7.x" || "${{github.ref}}" == "refs/heads/7.x" ]]; then
+            echo "DOCSEARCH_INDEX=expressionengine7" >> "$GITHUB_OUTPUT"
+          else
+            echo "DOCSEARCH_INDEX=expressionengine7_staging" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Update Docsearch Index
+        uses: richardrigutins/replace-in-files@v2
+        with:
+          search-text: "docsearch_index: 'expressionengine'"
+          replacement-text: "docsearch_index: '${{steps.setup_vars.outputs.DOCSEARCH_INDEX}}'"
+          files: ./config.yml
+
+      - name: Install NPM and build
+        run: |
+          npm install
+          npm run build
+
+      - name: Archive Build files
+        uses: actions/upload-artifact@v4
+        with:
+          name: EEDocs7.latest
+          path: build

.github/workflows/search.yml

@@ -0,0 +1,48 @@
+name: Update Search
+
+on:
+  workflow_dispatch:
+
+jobs:
+  search:
+    name: Build Search Index
+    runs-on: ubuntu-latest
+    steps:
+        - name: Checkout code
+          uses: actions/checkout@v4
+
+        - name: Setup Variables
+          run: |
+            if [[ "${{github.base_ref}}" == "7.x" || "${{github.ref}}" == "refs/heads/7.x" ]]; then
+              echo "DOCSEARCH_INDEX=expressionengine7" >> "$GITHUB_ENV"
+              echo "DOCS_URL=https://docs.expressionengine.com/latest" >> "$GITHUB_ENV"
+            else
+              echo "DOCSEARCH_INDEX=expressionengine7_staging" >> "$GITHUB_ENV"
+              echo "::add-mask::${{secrets.STAGING_DOCS_DOMAIN}}"
+              echo "DOCS_URL=${{secrets.STAGING_DOCS_URL}}" >> "$GITHUB_ENV"
+            fi
+
+        - name: Configure Docsearch Index
+          uses: richardrigutins/replace-in-files@v2
+          with:
+            search-text: "\"index_uid\": \"expressionengine\""
+            replacement-text: "\"index_uid\": \"${{ env.DOCSEARCH_INDEX }}\""
+            files: ./search.config.json
+
+        - name: Configure Docs Url
+          uses: richardrigutins/replace-in-files@v2
+          with:
+            search-text: "https://docs.expressionengine.com/latest"
+            replacement-text: ${{ env.DOCS_URL }}
+            files: ./search.config.json
+
+        - name: Scrape Docs
+          env:
+            HOST_URL: ${{ secrets.MEILISEARCH_HOST_URL }}
+            API_KEY: ${{ secrets.MEILISEARCH_API_KEY }}
+          run: |
+            docker run -t --rm \
+            -e MEILISEARCH_HOST_URL=$HOST_URL \
+            -e MEILISEARCH_API_KEY=$API_KEY \
+            -v ./search.config.json:/docs-scraper/search.config.json \
+            getmeili/docs-scraper:latest pipenv run ./docs_scraper search.config.json

README.md

@@ -34,6 +34,24 @@ To build the theme assets, run `npm run buildAssets`. You can also dynamically r
 
 Manually load `/build/index.html` in your browser to view your local build. For example, `file:///Users/<username>/Documents/ExpressionEngine-User-Guide/build/index.html`. You can use the side navigation to navigate to different local files, but the search functionality always takes you to the live version at docs.expressionengine.com.
 
+## Using DocSearch Locally
+
+First you will need to choose a docsearch index name to use for your local testing and set that in `config.yml`
+
+Then you will need to build the docs and serve a local copy.  For simplicity's sake we recommend using the node http-server like this `npx http-server -o`
+
+Next you will need to update all the urls in `search.config.json` to point at your local copy of the documentation.  Do a find/replace on `https://docs.expressionengine.com/latest` => `http://localhost:8080`.  You will also need to update the `allowed_domains` array to include this new url. (If you are on a mac you may need to use `http://host.docker.internal:8080` instead so that the scraper container can connect to the docs on your local http-server.)
+
+Finally you can scrape your local docs with the following docker command
+
+```
+docker run -t --rm --network=host \
+    -e MEILISEARCH_HOST_URL=https://docsearch.expressionengine.com \
+    -e MEILISEARCH_API_KEY={{ SECRET_KEY }} \
+    -v ./search.config.json:/docs-scraper/search.config.json \
+    getmeili/docs-scraper:latest pipenv run ./docs_scraper search.config.json
+```
+
 ## Contributing
 
 See something that needs fixing? Want to improve the user guide or make it more helpful? Great! Check out [CONTRIBUTING.md](CONTRIBUTING.md) for details.

config.yml

@@ -8,3 +8,5 @@ themeDir: theme
 customVariables:
   current_version: '7'
   current_year: 2024
+  docsearch_index: 'expressionengine'
+  docsearch_public_key: '7d283b55c1d7c0e5f340c71b5dfc751d8dc625708f29e582134f7643bc95dbd7'

docs/development/control-panel-js/globals.md

@@ -20,56 +20,56 @@ The elements of global `EE` JavaScript objects could vary depending on the Contr
 
 To add the element to global object, call [`ee()->javascript->set_global()`](development/legacy/libraries/javascript.md#set_globalvar-val--) function.
 
-### `BASE`
+## `BASE`
 
 Control Panel base URL.
 
     $.get(EE.BASE + '&C=login&M=lock_cp');
 
-### `CSRF_TOKEN`
+## `CSRF_TOKEN`
 
 The current [Cross Site Request Forgery](development/guidelines/security.md#cross-site-request-forgery) token
 
     headers: { 'X-CSRF-TOKEN': EE.CSRF_TOKEN },
 
-### `PATH_CP_GBL_IMG`
+## `PATH_CP_GBL_IMG`
 
 Path to `themes/ee/asset/img` directory
 
-### `THEME_URL`
+## `THEME_URL`
 
 URL to `themes/ee/cp` folder
 
-### `username`
+## `username`
 
 Username of currently logged in member
 
-### `lang`
+## `lang`
 
 Object of language strings available for JavaScript function in member's preferred language
 
     text: EE.lang.loading
 
-### `hasRememberMe`
+## `hasRememberMe`
 
 Indicates whether the "remember me" checkbox was toggled on when member logged in.
 
-### `cp.appVer`
+## `cp.appVer`
 
 The version number of ExpressionEngine release.
     data: {
         appVer: EE.cp.appVer,
     }
 
-### `site_id`
+## `site_id`
 
 ID of MSM site that is currently active in Control Panel
 
-### `site_name`
+## `site_name`
 
 The configured site name
 
-### `site_url`
+## `site_url`
 
 The URL to the site's front-end
 
@@ -81,7 +81,7 @@ The URL to the site's front-end
         }
     ]
 
-### `fileManagerCompatibilityMode`
+## `fileManagerCompatibilityMode`
 
 Indicates whether File Manager is running in [Compatibility Mode](control-panel/file-manager/file-manager.md#compatibility-mode).
 

docs/development/extension-hooks/api/channel-fields.md

@@ -13,7 +13,7 @@ lang: php
 
 # Channel Fields API Extension Hooks
 
-### `custom_field_modify_data(EE_Fieldtype $ft, $method, $data)`
+## `custom_field_modify_data(EE_Fieldtype $ft, $method, $data)`
 
 | Parameter | Type     | Description                                         |
 | --------- | -------- | --------------------------------------------------- |

docs/development/extension-hooks/api/template-structure.md

@@ -9,6 +9,6 @@
 
 # Template Structure API Extension Hooks
 
-### `template_types`
+## `template_types`
 
 See the Output library's [template_types](development/extension-hooks/cp/design.md#template_types).

docs/development/extension-hooks/cp/admin-content.md

@@ -13,9 +13,9 @@ lang: php
 
 # Admin Content Controller Extension Hooks
 
-[TOC=3]
+[TOC=2]
 
-### `category_delete($cat_ids)`
+## `category_delete($cat_ids)`
 
 | Parameter | Type    | Description                         |
 | --------- | ------- | ----------------------------------- |
@@ -28,7 +28,7 @@ How it's called:
 
     ee()->extensions->call('category_delete', $cat_ids);
 
-### `category_save($cat_id, $data)`
+## `category_save($cat_id, $data)`
 
 | Parameter       | Type    | Description          |
 | --------------- | ------- | -------------------- |
@@ -42,6 +42,6 @@ How it's called:
 
     ee()->extensions->call('category_save', $cat_id, $category_data);
 
-### `foreign_character_conversion_array`
+## `foreign_character_conversion_array`
 
 See Content_publish's `foreign_character_conversion_array`.

docs/development/extension-hooks/cp/css.md

@@ -13,7 +13,7 @@ lang: php
 
 # CSS Controller Extension Hooks
 
-### `cp_css_end()`
+## `cp_css_end()`
 
 | Parameter | Type     | Description                            |
 | --------- | -------- | -------------------------------------- |

docs/development/extension-hooks/cp/design.md

@@ -13,7 +13,7 @@ lang: php
 
 # Design Controller Extension Hooks
 
-### `template_types()`
+## `template_types()`
 
 | Parameter | Type    | Description                            |
 | --------- | ------- | -------------------------------------- |

docs/development/extension-hooks/cp/javascript.md

@@ -13,7 +13,7 @@ lang: php
 
 # Javascript Controller Extension Hooks
 
-### `cp_js_end()`
+## `cp_js_end()`
 
 | Parameter | Type     | Description                                       |
 | --------- | -------- | ------------------------------------------------- |

docs/development/extension-hooks/cp/login.md

@@ -13,9 +13,9 @@ lang: php
 
 # Login Controller Extension Hooks
 
-[TOC=3]
+[TOC=2]
 
-### `login_authenticate_start()`
+## `login_authenticate_start()`
 
 | Parameter | Type   |
 | --------- | ------ |
@@ -28,7 +28,7 @@ How it's called:
     $this->extensions->call('login_authenticate_start');
     if ($this->extensions->end_script === TRUE) return;
 
-### `cp_member_login($hook_data)`
+## `cp_member_login($hook_data)`
 
 | Parameter   | Type     | Description                                                                                                      |
 | ----------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
@@ -42,7 +42,7 @@ How it's called:
     ee()->extensions->call('cp_member_login', $this->_hook_data());
     if (ee()->extensions->end_script === TRUE) return;
 
-### `cp_member_logout()`
+## `cp_member_logout()`
 
 | Parameter | Type   |
 | --------- | ------ |
@@ -55,7 +55,7 @@ How it's called:
     $this->extensions->call('cp_member_logout');
     if ($this->extensions->end_script === TRUE) return;
 
-### `cp_member_reset_password()`
+## `cp_member_reset_password()`
 
 | Parameter | Type   |
 | --------- | ------ |