Replace site search with Pagefind - #2096
Open
haranrk wants to merge 1 commit into
Open
Conversation
✅ Deploy Preview for adk-docs-preview ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
haranrk
force-pushed
the
search/pagefind
branch
from
August 9, 2026 22:47
f8e7675 to
52103c6
Compare
Material's search ranked identifier queries badly, split one page across a row per heading, and showed only the first handful of matches. Pagefind indexes at build time, groups sub-results under their page, and pages through the whole result set. hooks/pagefind.py marks each page's content <article> with data-pagefind-body and runs the indexer over the built site. It fails the build on six conditions: the anchor missing, nothing marked, marked and indexed counts disagreeing, an exclude selector matching no page, a UI asset not emitted, and the ranking API gone from the bundle. MKDOCS_PAGEFIND_SKIP=1 skips indexing for a faster `mkdocs serve`, warns so that --strict fails pull requests, and is refused under gh-deploy, which publishes without --strict. The header hosts Pagefind's own modal and trigger components, so there is little UI to own. overrides/main.html raises termSimilarity so "LlmAgent" beats pages that merely say "agent" often, mirrors Material's colour scheme onto data-pf-theme, clears the search input on close around an upstream bug, and restores the / and s shortcuts that left with the old plugin. The lunr-specific CSS is gone.
haranrk
force-pushed
the
search/pagefind
branch
from
August 10, 2026 23:33
52103c6 to
df24634
Compare
This was referenced Aug 14, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Replaces MkDocs Material's lunr search with Pagefind 1.5.2.
Three problems with search today: ranking surfaces the wrong page, several hits from one page appear as unrelated entries, and the header dropdown caps what you can see. This fixes all three and drops the multi-megabyte
search_index.jsonevery visitor downloads up front.Pagefind ships a Python wheel, so the build stays pip-only and CI is unchanged.
Screenshots
Searching
LlmAgent. One card per page, with the matching headings nested beneath it, and the whole result set scrolls.Dark mode
The ranking playground, written only under
MKDOCS_PAGEFIND_PLAYGROUND=1. It scores the LLM agents page above workflow patterns at thetermSimilarity: 2.0this PR ships.What changed
hooks/pagefind.py(new) marks each page's indexable region, runs the indexer inon_post_build, and fails the build if the output is wrong.mkdocs.ymldrops thesearchplugin and registers the hook.overrides/swaps Material's search button for Pagefind's modal, sets ranking, and mirrors dark mode.docs/stylesheets/custom.cssremoves dead.md-searchrules and adds--pf-*theming.requirements.txtpinspagefind[bin]==1.5.2.Indexing reads built HTML, so it needs no knowledge of markdown, macros, or redirects, and behaves the same under
build,serve,--dirty, Netlify previews, andgh-deploy.Scope
226 handwritten pages. The generated API reference under
docs/api-reference/stays unindexed, as it is today. Any page can opt out withsearch: exclude: truefront matter.Verified in a browser
LlmAgentreturns the LLM agents page; with default ranking it returns workflow patterns, so the one tuned parameter (termSimilarity: 2.0) is doing real work.Cmd/Ctrl+K,/, orsopens search.Build guards
The failure worth preventing is a green build shipping dead search, so six conditions abort the build. Each was verified by deliberately breaking it.
<article>anchor stopped matching, after a theme change.--exclude-selectorsno longer appears in any indexed page, which is how fused tokens would silently return.gh-deployadditionally refuses to publish if indexing was skipped.Known tradeoffs
memory,a2a,bigquery, andcallbacksreturn a deeper page rather than the section overview.?h=arrival highlighting is gone. Pagefind's equivalent costs 44 KB on every page load, and results already land on the matching heading.MKDOCS_PAGEFIND_SKIP=1is the local escape hatch, and is deliberately ineffective on the paths that ship.