Skip to content

Reuse search entries of unchanged pages in mkdocs serve - #20

Merged
shenxianpeng merged 1 commit into
mainfrom
claude/project-thread-epdfwi
Nov 2, 2026
Merged

shenxianpeng merged 1 commit into
mainfrom
claude/project-thread-epdfwi

Conversation

@shenxianpeng

@shenxianpeng shenxianpeng commented Nov 2, 2026 •

Copy link
Copy Markdown
Member

On every mkdocs serve rebuild, the search plugin parsed the HTML of every page again with HTMLParser. On a 1,000-page site that took about 1.8 s of a 5.7 s rebuild, even when only one page changed.

mkdocs-ng 1.11 keeps a render cache during mkdocs serve (mkdocs.structure.render_cache, mkdocs-ng#131 and #145), and its own search plugin already reuses entries through RenderCache.memo. This does the same for Material's search plugin. The key holds everything the entries are computed from: the page URL, title, HTML, TOC, the title, tags and search.boost front matter, and the jieba settings. With older mkdocs-ng, or with mkdocs build, nothing changes.

Measured on the 1,000-page benchmark site (4 cores):

  • serve rebuild: 5.7 s → 3.8 s, of which the search plugin went from 1.8 s to 0.2 s
  • edit → page served (end to end): 5.9 s → 4.1 s
  • after adding a heading to one page, search/search_index.json from the serve rebuild is byte for byte the same as from a clean build

Changelog: added a 9.8.1 Unreleased entry in docs/changelog/index.md and CHANGELOG.

The search plugin parsed the HTML of every page again on each serve rebuild,
which took about a third of the rebuild time on large sites. With mkdocs-ng
1.11, keep the entries of a page in mkdocs' render cache, keyed on everything
they are computed from, and reuse them while the page is unchanged. The
search index is byte for byte the same.

With 1,000 pages, an edited page shows up after 4.1 s instead of 5.9 s.
@shenxianpeng shenxianpeng self-assigned this Nov 2, 2026
@shenxianpeng
shenxianpeng merged commit c066c52 into main Nov 2, 2026
5 checks passed
@shenxianpeng
shenxianpeng deleted the claude/project-thread-epdfwi branch November 2, 2026 20:08
@shenxianpeng shenxianpeng mentioned this pull request Nov 11, 2026

This branch was previously deployed

1 inactive deployment
pypi — c857549c Deployed Nov 2, 2026 by shenxianpeng via python #42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant