[WIP] Orama search

.github/workflows/deploy-orama-search.yml

@@ -0,0 +1,91 @@
+name: Deploy Orama Search Index
+
+on:
+  push:
+    branches: [main]
+    paths:
+      # Only trigger when documentation content changes
+      - "runtime/**/*.md"
+      - "deploy/**/*.md"
+      - "examples/**/*.md"
+      - "subhosting/**/*.md"
+      - "lint/**/*.md"
+      - "reference_gen/**"
+      # Or when the build configuration changes
+      - "deno.json"
+      - "orama/**"
+
+  # Allow manual triggering for testing
+  workflow_dispatch:
+    inputs:
+      force_deploy:
+        description: "Force deploy even without content changes"
+        required: false
+        default: false
+        type: boolean
+
+jobs:
+  deploy-search-index:
+    name: Generate and Deploy Search Index
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          # Fetch more history for content change detection
+          fetch-depth: 2
+
+      - name: Setup Deno
+        uses: denoland/setup-deno@v1
+        with:
+          deno-version: v1.x
+
+      - name: Check for content changes
+        id: changes
+        run: |
+          if [ "${{ github.event.inputs.force_deploy }}" = "true" ]; then
+            echo "Force deploy requested"
+            echo "content_changed=true" >> $GITHUB_OUTPUT
+          else
+            # Check if any content files changed in the last commit
+            CHANGED=$(git diff --name-only HEAD~1 HEAD | grep -E '\.(md|json)$|^reference_gen/|^orama/' || echo "")
+            if [ -n "$CHANGED" ]; then
+              echo "content_changed=true" >> $GITHUB_OUTPUT
+              echo "Content files changed:"
+              echo "$CHANGED" | sed 's/^/  /'
+            else
+              echo "content_changed=false" >> $GITHUB_OUTPUT
+              echo "  No content changes detected - skipping search index update"
+            fi
+          fi
+
+      - name: Generate comprehensive search index
+        if: steps.changes.outputs.content_changed == 'true'
+        run: |
+          echo "Generating comprehensive Orama search index..."
+          deno task generate:orama:full
+
+      - name: Upload and deploy to Orama Cloud
+        if: steps.changes.outputs.content_changed == 'true'
+        run: |
+          echo "Uploading search index to Orama Cloud..."
+          deno task upload:orama static/orama-index-full.json --deploy
+        env:
+          ORAMA_INDEX_ID: ${{ secrets.ORAMA_INDEX_ID }}
+          ORAMA_PRIVATE_API_KEY: ${{ secrets.ORAMA_PRIVATE_API_KEY }}
+
+      - name: Report deployment success
+        if: steps.changes.outputs.content_changed == 'true'
+        run: |
+          echo "Search index deployment completed successfully!"
+          echo "Updated search includes:"
+          echo "  Documentation pages"
+          echo "  API references (Deno, Web, Node.js)"
+          echo "  Total searchable documents: ~5,856"
+
+      - name: Skip deployment message
+        if: steps.changes.outputs.content_changed == 'false'
+        run: |
+          echo "No content changes detected - search index deployment skipped"
+          echo "To force a deployment, use the 'workflow_dispatch' trigger with force_deploy=true"

.gitignore

@@ -14,5 +14,9 @@ reference_gen/types
 static/llms.txt
 static/llms-full.txt
 
+# Orama search index files (generated at build time)
+static/orama-index.json
+static/orama-index-*.json
+
 .DS_Store
 .env

README.md

@@ -230,6 +230,69 @@ this command:
 git shortlog -s -n
 ```
 
+## Orama Search Configuration
+
+1. **Sign up for Orama Cloud**: Go to
+   [https://cloud.oramasearch.com/](https://cloud.oramasearch.com/) and create
+   an account.
+
+2. **Create a new index**:
+   - In the Orama dashboard, create a new index
+   - Set the data source to docs.deno.com or upload the documentation content
+     directly
+
+3. **Get your credentials**:
+   - In your Orama dashboard, you'll find your **Endpoint URL** and **Public API
+     Key**
+   - These are safe to include in frontend applications
+
+4. **Configure the search**:
+   - Open `search.client.ts`
+   - Replace `YOUR_ORAMA_ENDPOINT` with your actual endpoint URL
+   - Replace `YOUR_ORAMA_API_KEY` with your actual public API key
+
+### Data Sources
+
+For the Deno docs, we have several options:
+
+#### Option 1: Web Crawler (Recommended)
+
+- Use Orama's built-in web crawler to index your documentation site
+- Go to Data Sources → Web Crawler in your Orama dashboard
+- Add your site URL (e.g., `https://docs.deno.com`)
+- Configure crawling rules if needed
+
+#### Option 2: Static Files
+
+- Export your documentation content as JSON
+- Upload it directly to Orama
+- This gives you more control over what gets indexed
+
+#### Option 3: API Integration
+
+- Use Orama's REST API to programmatically add/update content
+- Useful to integrate with our build process
+
+### Configuration Example
+
+In `search.client.ts`, update the ORAMA_CONFIG object:
+
+```typescript
+const ORAMA_CONFIG = {
+  endpoint: "https://cloud.orama.com/v1/indexes/your-index-id",
+  apiKey: "your-public-api-key-here",
+};
+```
+
+### Customization
+
+We can customize the search experience by modifying:
+
+- **Search modes**: Change between "fulltext", "vector", or "hybrid" search
+- **Result limit**: Adjust how many results to show
+- **UI styling**: Modify the CSS classes in the search components
+- **Result formatting**: Change how search results are displayed
+
 ## Deployment
 
 The `docs.deno.com` site is updated with every push to the `main` branch, which

_components/Header.tsx

@@ -57,7 +57,7 @@ export default function (
             </a>
           ))}
         </nav>
-        <div className="flex items-center gap-x-2 sm:gap-x-4 ml-auto">
+        <div className="flex items-center gap-x-2 sm:gap-x-4 ml-auto w-full max-w-80">
           <data.comp.SearchInput />
           <data.comp.ThemeToggle />
           <data.comp.Hamburger />

_components/SearchInput.tsx

@@ -1,23 +1,76 @@
 export default function SearchInput() {
   return (
-    <>
-      <form
-        action="https://www.google.com/search"
-        method="get"
-        className="mb-0"
-        target="_blank"
-      >
+    <div className="md:relative w-full">
+      {/* ☝️ That md:relative class is crucial for making the search bar pop up in the right place. Don't change it, or add any other positioning classes, unless you're ready to account for positioning across all breakpoints. */}
+      <div className="relative">
         <input
           type="search"
-          name="q"
-          id="search-str"
           placeholder="Search"
-          className="w-full min-w-24 rounded-lg text-sm leading-normal pt-1 pr-3 pb-1 pl-8 border transition-all duration-150
-          text-foreground-primary border-foreground-tertiary hover:bg-background-secondary focus:bg-background-secondary"
-          style="background: url(/img/search.svg) no-repeat 0.5em 50%; background-size: 1em; background-color: var(--color-foreground-quaternary);"
+          id="orama-search-input"
+          className="w-full min-w-24 rounded-lg placeholder:text-sm text-base leading-normal p-1 pl-8 border transition-all duration-150
+          text-foreground-primary border-foreground-secondary hover:bg-background-secondary focus:bg-background-secondary focus:outline-offset-1"
+          style="background: url(/img/search.svg) no-repeat 0.5em 50%; background-size: 1.25em; background-color: var(--color-background-raw);"
         />
-        <input type="hidden" name="q" id="q" value="site:deno.com" />
-      </form>
-    </>
+        <kbd
+          id="search-key"
+          className="hidden xs:flex pointer-events-none absolute font-sans rounded-sm top-1 right-1 bottom-1 w-auto border-1 border-foreground-tertiary border-b-2 border-r-2 bg-background-primary text-foreground-secondary text-center text-xs font-bold p-2 items-center justify-center dark:bg-background-secondary dark:border-gray-700"
+        >
+          ⌘K
+        </kbd>
+        <div
+          id="orama-search-loading"
+          className="absolute left-2 top-1/2 transform -translate-y-1/2 hidden bg-background-raw"
+        >
+          <div className="animate-spin rounded-full h-4 w-4 border-2 border-transparent border-r-foreground-primary bg-background-raw" />
+        </div>
+        <div
+          className="sr-only"
+          aria-live="polite"
+          id="orama-results-announcer"
+        >
+          {/* Text updated by JavaScript. */}
+        </div>
+      </div>
+
+      {/* Enhanced Popover for Search Results */}
+      <div
+        id="orama-search-results"
+        className="absolute inset-2 left-2 right-2 h-[calc(100vh-8rem)] top-10 md:top-full md:left-auto md:right-0 mt-2 bg-background-raw border border-foreground-tertiary rounded-xl shadow-2xl z-50 md:max-h-128 overflow-hidden hidden md:min-w-160 max-w-2xl"
+      >
+        <div
+          id="orama-search-results-content"
+          className="overflow-y-auto h-full"
+        >
+          {/* Results will be populated via JavaScript */}
+        </div>
+
+        {/* Footer with search tips */}
+        <div className="border-t border-foreground-tertiary bg-background-secondary px-4 py-2 sticky bottom-0">
+          <div className="flex items-center gap-6 text-xs text-foreground-secondary">
+            <span>
+              <kbd className="px-1.5 py-0.5 text-xs font-semibold text-foreground-secondary bg-background-primary border-r-2 border-b-2 border border-foreground-tertiary rounded mr-1">
+                <span aria-hidden="true">↑↓</span>
+                <span className="sr-only">Up or down to</span>
+              </kbd>
+              navigate
+            </span>
+            <span>
+              <kbd className="px-1.5 py-0.5 text-xs font-semibold text-foreground-secondary bg-background-primary border-r-2 border-b-2 border border-foreground-tertiary rounded mr-1">
+                <span aria-hidden="true">↵</span>
+                <span className="sr-only">Enter to</span>
+              </kbd>
+              select
+            </span>
+            <span>
+              <kbd className="px-1.5 py-0.5 text-xs font-semibold text-foreground-secondary bg-background-primary border-r-2 border-b-2 border border-foreground-tertiary rounded mr-1">
+                <span aria-hidden="true">ESC</span>
+                <span className="sr-only">Escape to</span>
+              </kbd>
+              close
+            </span>
+          </div>
+        </div>
+      </div>
+    </div>
   );
 }

_includes/layout.tsx

@@ -61,6 +61,7 @@ export default function Layout(data: Lume.Data) {
         <script type="module" defer src="/copy.client.js"></script>
         <script type="module" defer src="/tabs.client.js"></script>
         <script type="module" defer src="/feedback.client.js"></script>
+        <script type="module" defer src="/search.client.js"></script>
         <script
           async
           src="https://www.googletagmanager.com/gtm.js?id=GTM-5B5TH8ZJ"

deno.json

@@ -15,7 +15,8 @@
     "googleapis": "npm:googleapis@^144.0.0",
     "postcss": "npm:postcss@^8.5.6",
     "prismjs": "npm:[email protected]",
-    "tailwindcss": "npm:tailwindcss@^4.1.11"
+    "tailwindcss": "npm:tailwindcss@^4.1.11",
+    "@orama/core": "jsr:@orama/core@^1.2.4"
   },
   "tasks": {
     "serve": "deno run --env-file -A lume.ts -s",
@@ -56,6 +57,34 @@
     "generate:llms:site": {
       "description": "Generate LLM-friendly documentation files directly in the _site directory",
       "command": "deno run -A generate_llms_files.ts _site"
+    },
+    "generate:orama": {
+      "description": "Generate Orama search index JSON file for uploading to Orama Cloud",
+      "command": "deno run -A orama/generate.ts"
+    },
+    "generate:orama:site": {
+      "description": "Generate Orama search index directly in the _site directory",
+      "command": "deno run -A orama/generate.ts _site"
+    },
+    "generate:orama:full": {
+      "description": "Generate comprehensive Orama index including API reference documentation",
+      "command": "deno run -A orama/generate_orama_index_full.ts"
+    },
+    "generate:orama:full:site": {
+      "description": "Generate comprehensive Orama index directly in the _site directory",
+      "command": "deno run -A orama/generate_orama_index_full.ts _site"
+    },
+    "upload:orama": {
+      "description": "Upload generated Orama index to Orama Cloud (requires ORAMA_INDEX_ID and ORAMA_PRIVATE_API_KEY env vars)",
+      "command": "deno run -A orama/upload_orama_index.ts"
+    },
+    "upload:orama:full": {
+      "description": "Upload comprehensive Orama index (orama-index-full.json) to Orama Cloud",
+      "command": "deno run -A orama/upload_orama_index.ts --full"
+    },
+    "analyze:orama": {
+      "description": "Analyze the generated Orama index to check content quality and statistics",
+      "command": "deno run -A orama/analyze_orama_index.ts"
     }
   },
   "compilerOptions": {
@@ -72,7 +101,8 @@
   },
   "exclude": [
     "_site",
-    "reference_gen"
+    "reference_gen",
+    "orama"
   ],
   "nodeModulesDir": "auto"
 }