Skip to main content

Search Improvements - Implementation Guide

Current Status​

I've implemented a search grouping solution that will group and order search results. However, there are some limitations with the search plugin that need to be addressed.

What Was Implemented​

1. ✅ Removed Category Dropdown​

  • Removed: searchContextByPaths configuration
  • Result: The confusing dropdown on the right side is now gone
  • File: docusaurus.config.ts

2. ✅ Increased Context Length​

  • Changed: searchResultContextMaxLength from 50 to 150 characters
  • Result: More preview text shown in results
  • File: docusaurus.config.ts

3. ✅ Created Result Grouping Module​

  • Created: src/client-modules/group-search-results-simple.js
  • What it does:
    • Detects search results in the DOM
    • Groups them by content type (User Guide, API v2, API v1, etc.)
    • Reorders groups (User Guide first)
    • Adds section headers between groups
    • Adds colored left borders

4. ✅ Page Description Script​

  • Created: scripts/add-page-descriptions.js
  • Usage: npm run add-descriptions
  • What it does: Extracts first paragraph from pages and adds as description in frontmatter

Known Limitations​

1. Content Preview May Not Show​

Issue: The search plugin (@easyops-cn/docusaurus-search-local) indexes content but may not display descriptions in the default template.

Why: The plugin's SuggestionTemplate.js doesn't have a built-in field for showing page descriptions from frontmatter.

Solution Options: A. Add descriptions to page content - Put the description as the first paragraph B. Swizzle the SearchBar component - Override the plugin's template (complex) C. Use a different search plugin - Like Algolia DocSearch (requires setup)

2. Grouping Timing​

Issue: The grouping runs after results appear, so there may be a brief flicker.

Why: We're post-processing the plugin's HTML output.

Solution: This is acceptable for now, but ideally we'd modify the plugin's template directly.

Testing the Changes​

Step 1: Rebuild​

npm run clear
npm run build
npm run serve
  1. Open http://localhost:3000
  2. Click search or press Ctrl+K / Cmd+K
  3. Type a query like "deposit"
  4. You should see:
    • ✅ No dropdown on the right
    • ✅ Section headers (📖 User Guide, API v2 Reference, etc.)
    • ✅ Results grouped by type
    • ✅ User Guide results first
    • ✅ Colored left borders
    • ⚠️ Preview text (may or may not show descriptions)

Adding Page Descriptions​

Automatic Method​

# Preview what would be added
npm run add-descriptions:dry-run

# Actually add descriptions
npm run add-descriptions

Manual Method​

Add to any MDX file frontmatter:

---
id: my-page
title: "My Page Title"
description: "A concise summary of what this page contains for search results."
---

Your content here...

Next Steps to Improve Further​

Effort: Low - Medium Impact: High

  1. Run npm run add-descriptions to auto-generate descriptions
  2. Review and improve the generated descriptions
  3. Manually add descriptions to important pages
  4. The search plugin WILL index these descriptions
  5. They may appear in search results (depending on plugin version)

Option B: Swizzle SearchBar Component​

Effort: High Impact: High

  1. Copy the plugin's SearchBar component to src/theme/@easyops-cn/docusaurus-search-local/SearchBar/
  2. Modify SuggestionTemplate.js to include description field
  3. Update styles
  4. Test thoroughly

Command (may not work):

npm run swizzle @easyops-cn/docusaurus-search-local SearchBar -- --eject

Option C: Switch to Algolia DocSearch​

Effort: High Impact: Very High

Algolia provides excellent search with:

  • Built-in grouping and filtering
  • Rich previews with descriptions
  • Typo tolerance
  • Analytics

Requirements:

  • Apply for Algolia DocSearch (free for open source/docs)
  • Configure crawler
  • Update docusaurus.config.ts

Links:

File Summary​

Modified Files​

  1. docusaurus.config.ts

    • Removed searchContextByPaths (eliminates dropdown)
    • Increased searchResultContextMaxLength to 150
    • Changed to group-search-results-simple.js module

  2. src/css/_search.scss

    • Added styles for section headers
    • Dark mode support
    • Group spacing

Created Files​

  1. src/client-modules/group-search-results-simple.js

    • Groups and reorders search results
    • Adds section headers
    • Adds visual indicators

  2. scripts/add-page-descriptions.js

    • Generates descriptions from content
    • Adds to frontmatter

  3. package.json (updated)

    • Added npm run add-descriptions command
    • Added npm run add-descriptions:dry-run command

Current Search Flow​

1. User types query
   ↓
2. @easyops-cn/docusaurus-search-local searches indexes
   ↓
3. Plugin renders results (mixed order)
   ↓
4. group-search-results-simple.js detects results
   ↓
5. Script groups by URL pattern:
   - /docs/docs/ → User Guide
   - /api/api-v2/ → API v2
   - /api/api-v1/ → API v1
   - etc.
   ↓
6. Script reorders groups (User Guide first)
   ↓
7. Script adds section headers
   ↓
8. Script adds colored borders
   ↓
9. User sees organized results

Comparison: Before vs After​

Before ❌​

Search: "deposit"

[Mixed Results]
- Create Deposit Account (API)
- Deposit Accounts (Guide)
- GET /deposits (API)
- Deposit Products (Guide)
  • No organization
  • Random order
  • No visual grouping
  • Dropdown that doesn't help

After ✅​

Search: "deposit"

📖 USER GUIDE
────────────────────────────
┃ Deposit Accounts
┃ Learn about deposit accounts...
┃
┃ Deposit Products
┃ Configure deposit products...

API V2 REFERENCE
────────────────────────────
┃ Create Deposit Account
┃ POST /deposits endpoint...
┃
┃ GET /deposits
┃ List all deposit accounts...
  • ✅ Clear grouping
  • ✅ User Guide first
  • ✅ Section headers
  • ✅ Colored borders
  • ✅ No confusing dropdown

Troubleshooting​

Grouping Not Appearing​

  1. Clear browser cache (Ctrl+Shift+R / Cmd+Shift+R)
  2. Check browser console for errors
  3. Verify group-search-results-simple.js is loaded
  4. Try increasing the timeout in the module (line 122)

Descriptions Not Showing​

  1. Run npm run add-descriptions to add them
  2. Rebuild: npm run clear && npm run build
  3. Note: The plugin may not display descriptions depending on its template
  4. This is a known limitation - see "Next Steps" above
  1. Verify searchContextByPaths is removed from config
  2. Rebuild completely
  3. Clear .docusaurus folder: npm run clear

Recommendation​

For the best search experience similar to Stripe's docs, I recommend:

Short Term (Now):

  1. ✅ Use the current grouping solution
  2. ✅ Run npm run add-descriptions to add descriptions
  3. ✅ Manually improve key page descriptions

Medium Term (Next sprint):

  1. Consider swizzling the SearchBar to show descriptions
  2. Or evaluate switching to Algolia DocSearch

Long Term:

  1. Switch to Algolia DocSearch for professional-grade search
  2. Includes: faceted search, typo tolerance, analytics, better relevance

Support​

If you need help implementing any of the advanced options (swizzling or Algolia), let me know and I can provide detailed step-by-step instructions.