With the help of our awesome sponsors, I'm happy to announce that the 'Carolina Reaper' funding goal has been reached, which means that the brand new search is finding its way into the community edition!

Since this is a pretty major change, we're releasing the new search as part of a new major version, so we can also drop and refactor some things that are overdue. This issue will track the progress on the road from the beta to the final release of v9.

If you experience any problems, for now, please report them as a comment in this issue.

Installation

pip install mkdocs-material==9.0.0b4

Note – This is a beta release, so please test thoroughly before deploying to production.
Final release date will be January 2, 2023.

Additions and improvements

• Rewrite of search plugin with support for rich previews
• Added support for tokenizer lookahead
• Added support for better search highlighting
• Added support for excluding content from search
• Added support for configurable search pipeline
• Added support for offline search via offline plugin
• Added support for multiple instances of built-in tags plugin in 17186b4
• Added support for removing copy-to-clipboard button in 128e267
• Added support for removing footer navigation in 8fdd1ad
• Added support for button to view the source of a page in 28d64a2
• Improved readability of query string for search sharing in ee14964
• Improved stability of search plugin when using --dirtyreload
• Improved "more on this page" by making it sticky and stable when scrolling
• Updated Norwegian translations (via Fix: Norwegian translations #4647)
• Updated to MkDocs 1.4.2 in 17186b4

Removals

• Removed alternative admonition qualifiers in daffd08
• Removed :is selectors (in output) to allow for easier overriding of CSS in daffd08
• Removed legacy method for providing page title in feedback URL in 9979cbf
• Removed .title suffix on translations in 37250f1
• Removed support for indexing only titles in search

Fixes

• Fixed Korean language code (kr ko) in 5aebaaa
• Fixed detection of composition events in search interface
• Fixed search plugin not using title set via front matter
• Fixed search highlighting of tags in 24a3be8
• Fixed search sharing URL using post transformed string (with wildcards etc.)
• Fixed inability to query specific fields (e.g. tags:foo or title:bar)
• Fixed inability to exclude search terms (e.g. -foo or -title:bar)
• Fixed inability to use fuzzy modifier (e.g. foo~1 or title:bar~2)
• Fixed inability to boost specific terms (e.g. foo^2 or title:bar^4)
• Fixed inability to use leading wildcards (e.g. *foo or *title:bar)
• Fixed theme-color meta tag getting out-of-sync in 944180d
• Fixed prev/next page keyboard navigation when footer is not present in 763423d
• Fixed overflowing navigation tabs not being scrollable in 9fb3610
• Omit code block line numbers from search

Upgrading

Changes to mkdocs.yml

• Enable copy-to-clipboard button: the copy-to-clipboard buttons are now opt-in. If you wish to enable them for all code blocks, add the following lines to mkdocs.yml:

  theme:
    features:
      - content.code.copy

  You can also choose to enable them for specific code blocks, by adding a .copy class to the code block, like so:

  ``` { .py .copy }
  ...
  ```

  Similarily, if you enabled the button globally, but want to disable it for a specific code block use .no-copy:

  ``` { .py .no-copy }
  ...
  ```

• Enable edit and view source button: a "view source" button can be shown next to the "edit this page" button, both of which must now be explicitly enabled. The repo_url must also be given. Add the following lines to mkdocs.yml:

  repo_url: ...
  theme:
    features:
      - content.action.edit
      - content.action.view

• Enable navigation footer: the previous and next buttons in the footer are now opt-in. If you wish to keep them for your documentation, add the following lines to mkdocs.yml:

  theme:
    features:
      - navigation.footer

• Use Korean language: the Korean language code was kr, which is not correct. It was corrected to ko:

  theme:
    language: ko

• Use Norwegian languages: the Norwegian language code was no, was no renamed to nb.

  theme:
    language: nb # or nn

• Feedback widget URLs: the old, nameless placeholders were removed (after being deprecated for several months). If Make sure to switch to the new named placeholders {title} and {url}:

  https://github.com/.../issues/new/?title=[Feedback]+{title}+-+{url}

There should be no other changes to mkdocs.yml necessary. If you discover that you need to change other lines to make v9 work, please comment below, so we can add it to the list.

Changes to documents

• Alternate admonition qualifiers: to keep the size of the CSS down, we removed support for alternate admonition qualifiers. Please use the standard admonition qualifiers that are mentioned in our documentation.

Changes to customizations

If you've customized Material for MkDocs with theme overrides, and added your own partials, you need to adjust for some changes, as the translations keys got updated. Keys that end with .title have been stripped off the suffix, so footer.title now becomes footer. The reason is that those are mostly generic translations of components that may not only be used in title attributes. See the partial diff.

Closing thoughts

Version 9 is a pretty big release, which includes a completely rewritten search implementation. I'm super happy to finally give it into the hands of all users, so we can improve it even more. Before issuing the final release, I'll take the opportunity to refactor some edges that need a little polishing and incorporate your feedback.