Adding Full-Text Search to MkDocs

A docs site without working search forces readers to guess at nav paths, and the larger the site the worse the guessing gets. MkDocs ships a client-side search that is genuinely good up to a point, and swaps to a server-backed index when a site outgrows it. This how-to configures the built-in search well, then shows when and how to move to a heavier backend. It extends MkDocs for Internal Docs within Developer Portal Architecture & Frameworks.

Prerequisites

  • MkDocs with Material for MkDocs installed, which provides the richest search experience.
  • A site large enough that nav alone is not enough — typically dozens of pages or more.
  • If you plan to move beyond client-side search, a place to host an index (a small service or a hosted search product).
  • Content written with real headings, since search quality depends on document structure.
Prerequisites for MkDocs search Material for MkDocs, a site past nav scale, an index host if needed, and structured content enable good search. Material theme site past nav scale index host (if scaling) structured content Findable docs fast search
Search reads your headings — well-structured pages with descriptive H2s search far better than walls of undifferentiated prose.

Exact Configuration

  1. Enable and tune the built-in search plugin. Material’s search supports separators, prebuilt indexing, and language tuning.

    # mkdocs.yml
# Requires mkdocs-material >= 9.0
plugins:
  - search:
      separator: '[\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])'
      lang:
        - en
theme:
  name: material
  features:
    - search.suggest
    - search.highlight
    - search.share

  2. Boost important pages with front-matter so key docs rank first.

    ---
search:
  boost: 3
---
# Getting Started

  3. When client-side search stops scaling, exclude the built-in index and point at a backend instead.

    # mkdocs.yml — large sites moving to a hosted index
plugins:
  - search:
      # keep for local dev; disable indexing in CI build for prod
      prebuild_index: true
Client-side versus backend search Client-side search ships an index to the browser and suits most sites; a backend index scales to very large docs. Client-side (built-in) index shipped to browser zero infrastructure good to ~hundreds of pages Backend index index hosted server-side stays fast at scale needs a service
Client-side search downloads the whole index to the browser — fine for hundreds of pages, sluggish once that index grows into megabytes.

Validation

# Requires a built site and python
# 1. The search index was generated
mkdocs build && test -f site/search/search_index.json && echo "index present"
# Expected: index present

# 2. The index contains a term you know exists
grep -q "onboarding" site/search/search_index.json && echo "term indexed"
# Expected: term indexed

# 3. Index size is sane for client-side search
du -h site/search/search_index.json
# Expected: comfortably under ~1MB; larger suggests moving to a backend
MkDocs search validation checks The index is generated, contains known terms, and is a sane size for client-side delivery. Index generated search_index.json Term present known word found Size sane < ~1MB
Index size is the early-warning signal — when search_index.json creeps past a megabyte, plan the move to a backend.

Edge Cases & Troubleshooting

Symptom Root Cause Resolution
Search finds nothing Plugin disabled or index not built Confirm search is in plugins; rebuild
CamelCase terms not matched Default separator does not split them Add the camel-split pattern to separator
Search slow on first query Large index downloaded lazily Enable prebuild_index, or move to a backend
Non-English terms missed Language not configured Add the language code under lang
Irrelevant page ranks first No boosting Add search.boost front-matter to key pages
MkDocs search pitfalls by class Missing results and unmatched terms are config issues; slow queries and poor ranking are scale and tuning issues. Config nothing found camelCase miss → enable + separator Scale & tuning slow query poor ranking → backend + boost
Most "search is broken" reports on MkDocs are a missing separator pattern or a disabled plugin — check config before blaming scale.

Frequently Asked Questions

Do I need an external search service at all?

Most internal docs sites never do. Material’s client-side search is fast and offline-friendly up to hundreds of pages, and it needs zero infrastructure. Only reach for a backend when the index grows large enough to slow the first query, or when you want to unify docs search with the wider portal search covered elsewhere in the portal.

How does this relate to portal-wide search?

MkDocs search covers one docs site; portal-wide search indexes docs alongside services and APIs. When docs are published through TechDocs, the portal’s own collators index them into the shared search, so this page’s tuning matters most for the standalone MkDocs experience rather than the unified portal box.