docs(DocSearch): integrate Algolia DocSearch for better developer experience (#148)

* docs: integrate Algolia DocSearch (fixes #147)

* feat(.gitignore): ignore .env files

* feat(docusaurus.config.js, .env.example): update to match Algolia env vars

* feat(deploy.yml): update to expose Algolia env vars during docs build

* docs: add Algolia DocSearch and env example notes

* docs(getting-started): enhance clarity, wording & code examples

---------

Co-authored-by: Ryan-Millard <millardryandevon@gmail.com>

Author: Sriram2272

.github/workflows/deploy.yml

@@ -41,6 +41,10 @@ jobs:
         run: npm run build
 
       - name: Build Docusaurus site
+        env:
+          ALGOLIA_APP_ID: ${{ secrets.ALGOLIA_APP_ID }}
+          ALGOLIA_API_KEY: ${{ secrets.ALGOLIA_API_KEY }}
+          ALGOLIA_INDEX_NAME: ${{ secrets.ALGOLIA_INDEX_NAME }}
         run: |
           cd docs
           npm ci

.gitignore

@@ -28,6 +28,7 @@ dist-ssr
 
 src/data/contributor-credits.json
 
+.env
 # CMake build artifacts
 src/wasm/cmake-build/
 src/wasm/**/CMakeCache.txt

docs/.env.example

@@ -0,0 +1,3 @@
+ALGOLIA_APP_ID=
+ALGOLIA_API_KEY=
+ALGOLIA_INDEX_NAME=

docs/.gitignore

@@ -10,6 +10,7 @@
 
 # Misc
 .DS_Store
+.env
 .env.local
 .env.development.local
 .env.test.local

docs/docs/introduction/_category_.json

@@ -2,6 +2,9 @@
   "label": "📖 Introduction",
   "position": 2,
   "link": {
-    "type": "generated-index"
-  }
+    "type": "generated-index",
+    "title": "Introduction Overview",
+    "description": "A brief usage overview and introduction to development in Img2Num."
+  },
+  "collapsed": false
 }

docs/docs/introduction/getting-started.md

@@ -161,7 +161,6 @@ The section below will guide you through installing Docker on your operating sys
   </TabItem>
 
 </Tabs>
-
 </TabItem>
 
 <TabItem value="local" label="Local / Manual Setup">
@@ -258,6 +257,12 @@ You can choose to only install the dependencies for one portion of the app, but
         In order to call the `img2num` script that we will be using for Docker in the following sections,
         you need to stay in the root directory of the project since that is where the file is.
         :::
+        :::tip For Experienced Docker users
+        You can skip using the `img2num` script if you prefer using plain Docker commands -
+        the script is intended to help developers who don't want to use Docker directly.
+
+        It is recommended that you read the contents of the file for examples of the commands you can use.
+        :::
         <Tabs groupId="setup-scripts" defaultValue="bash">
           <TabItem value="bash" label="Bash (Linux / macOS / WSL / Git Bash)" default>
             ```bash title="Install all dependencies"
@@ -267,24 +272,42 @@ You can choose to only install the dependencies for one portion of the app, but
 
             ./img2num npm install --prefix ./docs
             ```
+
+            :::info
+            ```bash title="Try passing -h or --help as an argument to see the list of available script arguments"
+            ./img2num -h    # or --help (they are are the same)
+            ```
+            :::
           </TabItem>
 
           <TabItem value="batch" label="Batch (Windows CMD)">
-            ```bash title="Install all dependencies"
+            ```bat title="Install all dependencies"
             cd Img2Num
             .\img2num.bat npm install
 
             .\img2num.bat npm install --prefix ./docs
             ```
+
+            :::info
+            ```bat title="Try passing -h or --help as an argument to see the list of available script arguments"
+            .\img2num.bat -h    REM or --help (they are are the same)
+            ```
+            :::
           </TabItem>
 
           <TabItem value="powershell" label="PowerShell">
-            ```bash title="Install all dependencies"
+            ```ps1 title="Install all dependencies"
             cd Img2Num
             .\img2num.ps1 npm install
 
             .\img2num.ps1 npm install --prefix ./docs
             ```
+
+            :::info
+            ```ps1 title="Try passing -h or --help as an argument to see the list of available script arguments"
+            .\img2num.ps1 -h    # or --help (they are are the same)
+            ```
+            :::
           </TabItem>
         </Tabs>
       </TabItem>
@@ -376,6 +399,20 @@ You can choose to only install the dependencies for one portion of the app, but
   </TabItem>
 </Tabs>
 
+### Docs Search (Algolia DocSearch)
+
+The documentation site ships with `Algolia DocSearch` already configured.
+**You do not need Algolia credentials** to run the docs locally. If you do not provide credentials,
+the search box will be inactive in local development, which is expected.
+
+:::info
+You can ignore this feature as it only affects production builds.
+:::
+
+### Environment variables (.env.example)
+
+The docs site includes a `docs/.env.example` file to document the optional Algolia environment variables. For local development, you can safely leave these values blank, and you should never commit real secrets to the repository.
+
 ## Running the app for the first time
 
 This section will help you run both the main application and the documentation site for the first time.

docs/docusaurus.config.js

@@ -4,14 +4,33 @@
 // There are various equivalent ways to declare your Docusaurus config.
 // See: https://docusaurus.io/docs/api/docusaurus-config
 
+import { createRequire } from 'module';
 import { themes as prismThemes } from 'prism-react-renderer';
 import path from 'path';
 import webpackAliasPlugin from './plugins/webpack-alias/index.js';
 import { changelogSidebarGenerator } from './changelogSidebarGenerator.js';
 import remarkMath from 'remark-math';
 import rehypeKatex from 'rehype-katex';
 
-// This runs in Node.js - Don't use client-side code here (browser APIs, JSX...)
+const require = createRequire(import.meta.url);
+require('dotenv').config();
+
+const hasAlgoliaEnvDefined = process.env.ALGOLIA_APP_ID
+                          && process.env.ALGOLIA_API_KEY
+                          && process.env.ALGOLIA_INDEX_NAME;
+const algolia =
+  hasAlgoliaEnvDefined
+  ? {
+    appId: process.env.ALGOLIA_APP_ID,
+    apiKey: process.env.ALGOLIA_API_KEY,
+    indexName: process.env.ALGOLIA_INDEX_NAME,
+    contextualSearch: true,
+  }
+  : undefined;
+const algoliaHeadTag = {
+  name: 'algolia-site-verification',
+  content: 'DB4B5FEC1545D32B',
+};
 
 /** @type {import('@docusaurus/types').Config} */
 const config = {
@@ -124,6 +143,13 @@ const config = {
       colorMode: {
         respectPrefersColorScheme: true,
       },
+
+      metadata: [
+        algoliaHeadTag,
+      ],
+
+      algolia,
+
       navbar: {
         title: 'Img2Num',
         logo: {