Skip to content

Docs Search Service

This note defines the local-first global search service for the OVES MkDocs estate.

Goals

  • Keep documentation repo-native and independently publishable.
  • Reuse each site's native MkDocs search/search_index.json.
  • Provide one cross-site query API callable from any doc site.
  • Cleanly separate local and cloud URL resolution.

Runtime Model

  • Child sites publish native MkDocs search indexes.
  • docs-search harvests those indexes into a local SQLite FTS database.
  • Search clients call the service rather than browser-fetching every site registry.

Environment Split

  • DOCS_SEARCH_ENV=local
  • Harvests local docs proxy URLs such as http://127.0.0.1:8099/internal/<repo>/search/search_index.json
  • Returns local proxy result URLs
  • DOCS_SEARCH_ENV=cloud
  • Harvests canonical URLs such as https://docs.omnivoltaic.com/internal/<repo>/search/search_index.json
  • Returns canonical result URLs

Local Run

cd D:\github\consolidated-docs
python scripts/build_docs_search_registry.py
python -m uvicorn docs_search.app:app --host 127.0.0.1 --port 8105

Basic Checks

curl "http://127.0.0.1:8105/health"
curl "http://127.0.0.1:8105/sites"
curl "http://127.0.0.1:8105/search?q=ABS"