🚀 Material for MkDocs 9 – Beta

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 17186b49478e4ea17b1ede882c61439d8d4d8d1b
• Added support for removing copy-to-clipboard button in 128e26742
• Added support for removing footer navigation in 8fdd1ad52
• Added support for button to view the source of a page in 28d64a289
• Improved readability of query string for search sharing in ee149649
• 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 #4647)
• Updated to MkDocs 1.4.2 in 17186b49478e4ea17b1ede882c61439d8d4d8d1b

Removals

• Removed alternative admonition qualifiers in https://github.com/squidfunk/mkdocs-material/pull/4584/commits/daffd085f3bc35058ada32fad0a21b2d88ac0d3f
• Removed :is selectors (in output) to allow for easier overriding of CSS in daffd085f3bc35058ada32fad0a21b2d88ac0d3f
• Removed legacy method for providing page title in feedback URL in 9979cbf9ecf487588b3a2dc877e17916b8ea9abe
• Removed .title suffix on translations in 37250f1be
• Removed support for indexing only titles in search

Fixes

• Fixed Korean language code (kr ko) in 5aebaaa71
• 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 https://github.com/squidfunk/mkdocs-material/commit/944180d572ac6aab03f12e8c444f92f6c3bd0f33
• Fixed prev/next page keyboard navigation when footer is not present in 763423d30
• Fixed overflowing navigation tabs not being scrollable in 9fb36102
• 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.

[squidfunk]

Thanks for everybody testing the beta so far! Since it’s impossible to predict what will break down the line, I don’t think it’s a good idea to push this out before Christmas or even NYE. People are busy getting presents, and, in Germany, meeting in the evening to drink some Glühwein, so it’s probably not a good idea to impose such a major change upon them right now. We’ll move v9 out of beta at the beginning of next year.

If you already want to try it, no problem, just install the beta (see OP) and see if you run into any problems. You can already fix them on a separate branch, and then later, when v9 is out, just remove the b release modifier and you’re done.

Final release date will be January 2, 2023.

[squidfunk]

I just released the latest fixes as part of 9.0.0b3.