Search Configuration Guide¶

This guide covers the search functionality in MAID documentation, including the built-in MkDocs Material search and optional Algolia DocSearch for production deployments.

Built-in Search¶

MAID documentation uses MkDocs Material's built-in search, powered by lunr.js. This provides:

Client-side search: No server required, works offline
Full-text indexing: All documentation content is searchable
Stemming support: Search finds word variations (e.g., "running" matches "run")
Instant results: Fast search-as-you-type experience

Current Configuration¶

The search is configured in mkdocs.yml:

plugins:
  - search:
      separator: '[\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;'
      lang: en
      pipeline:
        - stemmer
        - stopWordFilter
        - trimmer

theme:
  features:
    - search.suggest      # Show search suggestions as you type
    - search.highlight    # Highlight search terms in results
    - search.share        # Enable shareable search links

Configuration Options¶

Separator Pattern¶

The separator pattern defines how text is tokenized for search:

[\s\-,:!=\[\]()"/]+ - Split on whitespace and common punctuation
(?!\b)(?=[A-Z][a-z]) - Split camelCase (e.g., "GameEngine" becomes "Game Engine")
\.(?!\d) - Split on dots except in version numbers
&[lg]t; - Handle HTML entities

Language Support¶

The lang option enables language-specific stemming. For multi-language support:

plugins:
  - search:
      lang:
        - en
        - es
        - de

Performance Impact

Each additional language adds 15-30KB to the JavaScript bundle.

Pipeline Functions¶

stemmer: Reduces words to root forms (e.g., "running" -> "run")
stopWordFilter: Removes common words (e.g., "the", "is", "at")
trimmer: Strips leading/trailing whitespace

Theme Features¶

Feature	Description
`search.suggest`	Shows likely completions for the last word typed
`search.highlight`	Highlights matching terms after clicking a result
`search.share`	Adds a button to copy a shareable link to the search

Keyboard Shortcuts¶

Key	Action
`/`	Open search
`Escape`	Close search
`Down Arrow`	Navigate to next result
`Up Arrow`	Navigate to previous result
`Enter`	Go to selected result
`Right Arrow`	Accept search suggestion

Page-Level Configuration¶

Boosting Pages¶

Make important pages rank higher in search results:

---
search:
  boost: 2
---

# Important Page Title

This page will rank higher in search results.

Values greater than 1 increase ranking, values less than 1 decrease it.

Excluding Pages¶

Exclude pages from search (useful for drafts or templates):

---
search:
  exclude: true
---

# Draft Page

This content will not appear in search results.

Excluding Sections¶

Exclude specific sections using the data-search-exclude attribute:

## Public Section

This content is searchable.

## Internal Notes { data-search-exclude }

This section is excluded from search.

Search Index¶

The search index is generated at build time in site/search/search_index.json. This file contains:

Document locations (URLs)
Document titles
Indexed text content
Custom boost values

Index Structure¶

{
  "config": {
    "lang": ["en"],
    "separator": "...",
    "pipeline": ["stopWordFilter"],
    "fields": {
      "title": {"boost": 1000.0},
      "text": {"boost": 1.0},
      "tags": {"boost": 1000000.0}
    }
  },
  "docs": [
    {
      "location": "getting-started/",
      "title": "Getting Started",
      "text": "..."
    }
  ]
}

Algolia DocSearch (Optional)¶

For production deployments with high traffic, consider Algolia DocSearch. This provides:

Server-side search with faster results
Better ranking algorithms
Search analytics
API-based architecture

Applying for DocSearch¶

Visit Algolia DocSearch
Submit your documentation URL
Wait for approval (free for open-source projects)

Configuration Template¶

Once approved, add to mkdocs.yml:

# Disable built-in search
plugins:
  # - search  # Comment out built-in search

extra:
  # Algolia DocSearch configuration
  algolia:
    application_id: YOUR_APP_ID
    api_key: YOUR_SEARCH_API_KEY
    index_name: maid-docs

extra_javascript:
  - https://cdn.jsdelivr.net/npm/@docsearch/js@3
  - javascripts/algolia-search.js

extra_css:
  - https://cdn.jsdelivr.net/npm/@docsearch/css@3

Create docs/javascripts/algolia-search.js:

document.addEventListener('DOMContentLoaded', function() {
  docsearch({
    container: '#docsearch',
    appId: 'YOUR_APP_ID',
    indexName: 'maid-docs',
    apiKey: 'YOUR_SEARCH_API_KEY',
  });
});

DocSearch Crawler Configuration¶

Algolia provides a crawler configuration template. Here's a starting point for MAID docs:

{
  "index_name": "maid-docs",
  "start_urls": [
    "https://maid-mud.org/docs/"
  ],
  "sitemap_urls": [
    "https://maid-mud.org/docs/sitemap.xml"
  ],
  "selectors": {
    "lvl0": {
      "selector": ".md-header .md-tabs__link--active",
      "global": true,
      "default_value": "Documentation"
    },
    "lvl1": ".md-content h1",
    "lvl2": ".md-content h2",
    "lvl3": ".md-content h3",
    "lvl4": ".md-content h4",
    "text": ".md-content p, .md-content li, .md-content td"
  },
  "strip_chars": " .,;:#",
  "custom_settings": {
    "separatorsToIndex": "_",
    "attributesForFaceting": ["language", "version", "tags"],
    "attributesToRetrieve": ["hierarchy", "content", "anchor", "url"]
  }
}

Testing Search¶

Local Testing¶

Build the documentation:
```
uv run mkdocs build
```
Serve locally:
```
uv run mkdocs serve
```
Open http://localhost:8000 and test search

Verification Checklist¶

[ ] Common terms return relevant results
[ ] API names are searchable (e.g., "GameEngine", "EventBus")
[ ] Code-related terms work (e.g., "async", "Component")
[ ] Search suggestions appear as you type
[ ] Search highlighting works on result pages
[ ] Keyboard shortcuts function correctly

Search Analytics¶

If using Algolia, monitor search analytics to:

Identify common searches with no results
Find opportunities to improve content
Track search trends over time

Troubleshooting¶

Search Not Working¶

Check JavaScript errors: Open browser console for errors
Verify index exists: Check site/search/search_index.json after build
Clear browser cache: Cached old search index can cause issues

Incomplete Results¶

Check page exclusions: Ensure pages aren't accidentally excluded
Verify content indexing: Long documents may be truncated
Check separator pattern: Complex terms might be split incorrectly

Slow Search¶

Reduce index size: Exclude non-essential pages
Optimize content: Remove duplicate content
Consider Algolia: Server-side search is faster for large sites