Add search using Typesense

Author: rafaeluphold

.env.typesense.sample

@@ -0,0 +1,30 @@
+# Example Local Docker:
+#
+# For Local Docker, the TYPESENSE_API_KEY and TYPESENSE_SEARCH_API_KEY
+# are the same as there's only one key to the local Typesense instance.
+#
+#   TYPESENSE_API_KEY=local_typesense_admin
+#   TYPESENSE_HOST=host.docker.internal
+#   TYPESENSE_PORT=8108
+#   TYPESENSE_PROTOCOL=http
+#   TYPESENSE_SEARCH_API_KEY=local_typesense_admin
+
+# Example Typesense Cloud:
+#
+# For Typesense Cloud, the TYPESENSE_API_KEY needs to have write access
+# to the Typesense cluster because it's used by the scraper to index the
+# content, while the TYPESENSE_SEARCH_API_KEY needs to have read-only
+# access to the Typesense cluster because it's used by the browser to
+# perform search queries.
+#
+#   TYPESENSE_API_KEY=<ADMIN_TYPESENSE_API_KEY>
+#   TYPESENSE_HOST=<TYPESENSE_CLUSTER.a1.typesense.net>
+#   TYPESENSE_PORT=443
+#   TYPESENSE_PROTOCOL=https
+#   TYPESENSE_SEARCH_API_KEY=<READ_ONLY_TYPESENSE_API_KEY>
+
+TYPESENSE_API_KEY=
+TYPESENSE_HOST=
+TYPESENSE_PORT=
+TYPESENSE_PROTOCOL=
+TYPESENSE_SEARCH_API_KEY=

.github/workflows/deploy.docusaurus.yml

@@ -15,7 +15,7 @@ jobs:
       pull-requests: write
 
     steps:
-    - name: Checkout code
+    - name: Checkout Code
       uses: actions/checkout@v3
 
     - name: Setup Node.js
@@ -24,11 +24,20 @@ jobs:
         node-version: 18
         cache: npm
 
-    - name: Install dependencies
+    - name: Install Dependencies
       run: npm ci
 
     - name: Build
       run: npm run build
+      env:
+        TYPESENSE_HOST: ${{ secrets.TYPESENSE_HOST }}
+        TYPESENSE_PORT: 443
+        TYPESENSE_PROTOCOL: https
+        TYPESENSE_SEARCH_API_KEY: ${{ secrets.TYPESENSE_SEARCH_API_KEY }}
+
+    - name: Write Deployment Marker
+      run: |
+        printf '{"deploymentId":"%s"}\n' '${{ github.run_id }}' > build/deployment.json
 
     - name: Publish to Cloudflare Pages
       id: cloudflare-pages
@@ -39,7 +48,31 @@ jobs:
         projectName: topper-docs
         directory: build
 
-    - name: Add comment
+    - name: Wait for Deployment
+      if: github.ref == 'refs/heads/master'
+      run: |
+        for attempt in $(seq 1 30); do
+          if curl -fsS "https://docs.topperpay.com/deployment.json?run=${{ github.run_id }}&attempt=$attempt" | grep -F '"deploymentId":"${{ github.run_id }}"' > /dev/null; then
+            exit 0
+          fi
+
+          echo "Site not updated yet, retrying ($attempt/30)."
+          sleep 10
+        done
+
+        echo "Timed out waiting for https://docs.topperpay.com/deployment.json to serve deploymentId ${{ github.run_id }}."
+        exit 1
+
+    - name: Index Docs in Typesense
+      if: github.ref == 'refs/heads/master'
+      run: npm run index
+      env:
+        TYPESENSE_API_KEY: ${{ secrets.TYPESENSE_API_KEY }}
+        TYPESENSE_HOST: ${{ secrets.TYPESENSE_HOST }}
+        TYPESENSE_PORT: 443
+        TYPESENSE_PROTOCOL: https
+
+    - name: Add Comment
       uses: mshick/add-pr-comment@v2
       with:
         message: |
@@ -48,5 +81,5 @@ jobs:
           |  Name | Link |
           |------ | ---- |
           | <span aria-hidden="true">🔨</span> Commit SHA | ${{ github.sha }} |
-          | <span aria-hidden="true">🔍</span> Deploy log | ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} |
+          | <span aria-hidden="true">🔍</span> Deploy Log | ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} |
           | <span aria-hidden="true">🚀</span> Preview URL | [${{ steps.cloudflare-pages.outputs.url }}](${{ steps.cloudflare-pages.outputs.url }}) |

.gitignore

@@ -1,4 +1,6 @@
-/build
-.docusaurus
 .cache-loader
+.docusaurus
+.env.typesense
+/build
+/typesense-data
 node_modules

README.md

@@ -1,8 +1,8 @@
 # topper-docs
 
-Public developer documentation for business users integrating with topper, built using [Docusaurus](https://docusaurus.io/).
+Public developer documentation for business users integrating with Topper, built using [Docusaurus](https://docusaurus.io/).
 
-## Running locally
+## Running Locally
 
 ```sh
 npm install

docusaurus.config.js

@@ -1,6 +1,12 @@
 const darkCodeTheme = require('prism-react-renderer').themes.dracula;
 const lightCodeTheme = require('prism-react-renderer').themes.github;
 
+const typesenseHost = process.env.TYPESENSE_HOST ?? 'localhost';
+const typesensePort = parseInt(process.env.TYPESENSE_PORT, 10) || 8108;
+const typesenseProtocol = process.env.TYPESENSE_PROTOCOL ?? 'http';
+const isLocalTypesense = (typesenseHost === 'localhost' || typesenseHost === 'host.docker.internal') && typesenseProtocol === 'http';
+const typesenseSearchApiKey = process.env.TYPESENSE_SEARCH_API_KEY ?? (isLocalTypesense ? 'local_typesense_admin' : undefined);
+
 const config = {
   baseUrl: '/',
   favicon: 'images/favicon.ico',
@@ -44,10 +50,23 @@ const config = {
       darkTheme: darkCodeTheme,
       theme: lightCodeTheme,
       additionalLanguages: ['java', "go", "python", "php"]
+    },
+    typesense: {
+      contextualSearch: true,
+      typesenseCollectionName: 'topper_docs', // Must match `index_name` in `typesense-docsearch-config.json`.
+      typesenseServerConfig: {
+        apiKey: typesenseSearchApiKey,
+        nodes: [{
+          host: typesenseHost,
+          port: typesensePort,
+          protocol: typesenseProtocol
+        }],
+      }
     }
   },
-  title: 'Topper - Developer docs',
-  url: 'https://docs.topperpay.com'
+  themes: ['docusaurus-theme-search-typesense'],
+  title: 'Topper - Developer Docs',
+  url: process.env.TOPPER_DOCS_URL ?? 'https://docs.topperpay.com'
 };
 
 module.exports = config;