# How to upgrade Upgrade to the latest version with: ``` pip install --upgrade --force-reinstall mkdocs-material ``` Show the currently installed version with: ``` pip show mkdocs-material ``` ## Upgrading from 8.x to 9.x This major release includes a brand new search implementation that is faster and allows for rich previews, advanced tokenization and better highlighting. It was available as part of Insiders for over a year, and now that the funding goal was hit, makes its way into the community edition. ### Changes to `mkdocs.yml` #### `content.code.copy` The copy-to-clipboard buttons are now opt-in and can be enabled or disabled per block. If you wish to enable them for all code blocks, add the following lines to `mkdocs.yml`: ``` yaml theme: features: - content.code.copy ``` #### `content.action.*` A "view source" button can be shown next to the "edit this page" button, both of which must now be explicitly enabled. Add the following lines to `mkdocs.yml`: ``` yaml theme: features: - content.action.edit - content.action.view ``` #### `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`: ``` yaml theme: features: - navigation.footer ``` #### `theme.language` The Korean and Norwegian language codes were renamed, as they were non-standard: - `kr` to `ko` - `no` to `nb` #### `feedback.ratings` The old, nameless placeholders were removed (after being deprecated for several months). Make sure to switch to the new named placeholders `{title}` and `{url}`: ``` https://github.com/.../issues/new/?title=[Feedback]+{title}+-+{url} ``` ### Changes to `*.html` files The templates have undergone a series of changes. If you have customized Material for MkDocs with theme extension, be sure to incorporate the latest changes into your templates. A good starting point is to [inspect the diff]. !!! warning "Built-in plugins not working after upgrade?" If one of the built-in plugins (search or tags) doesn't work anymore without any apparent error or cause, it is very likely related to custom overrides. [MkDocs 1.4.1] and above allow themes to namespace built-in plugins, which Material for MkDocs 9 now does in order to allow authors to use third-party plugins with the same name as built-in plugins. Search your overrides for [`"in config.plugins"`][in config.plugins] and add the `material/` namespace. Affected partials: - [`content.html`][content.html] - [`header.html`][header.html] [inspect the diff]: https://github.com/squidfunk/mkdocs-material/pull/4628/files#diff-3ca112736b9164701b599f34780107abf14bb79fe110c478cac410be90899828 [MkDocs 1.4.1]: https://github.com/mkdocs/mkdocs/releases/tag/1.4.1 [in config.plugins]: https://github.com/squidfunk/mkdocs-material/search?q=%22in+config.plugins%22 [content.html]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/partials/content.html [header.html]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/partials/header.html ## Upgrading from 7.x to 8.x ### What's new? - Added support for code annotations - Added support for anchor tracking - Added support for version warning - Added `copyright` partial for easier override - Removed deprecated content tabs legacy implementation - Removed deprecated `seealso` admonition type - Removed deprecated `site_keywords` setting (unsupported by MkDocs) - Removed deprecated prebuilt search index support - Removed deprecated web app manifest – use customization - Removed `extracopyright` variable – use new `copyright` partial - Removed Disqus integration – use customization - Switched to `:is()` selectors for simple selector lists - Switched autoprefixer from `last 4 years` to `last 2 years` - Improved CSS overall to match modern standards - Improved CSS variable semantics for fonts - Improved extensibility by restructuring partials - Improved handling of `details` when printing - Improved keyboard navigation for footnotes - Fixed #3214: Search highlighting breaks site when empty ### Changes to `mkdocs.yml` #### `pymdownx.tabbed` Support for the legacy style of the [Tabbed] extension was dropped in favor of the new, alternate implementation which has [better behavior on mobile viewports]: === "8.x" ``` yaml markdown_extensions: - pymdownx.tabbed: alternate_style: true ``` === "7.x" ``` yaml markdown_extensions: - pymdownx.tabbed ``` [Tabbed]: setup/extensions/python-markdown-extensions.md#tabbed [better behavior on mobile viewports]: https://twitter.com/squidfunk/status/1424740370596958214 #### `pymdownx.superfences` The `*-experimental` suffix must be removed from the [custom fence][SuperFences] class property, which is used to target code blocks to be rendered as [diagrams] using [Mermaid.js]: === "8.x" ``` yaml markdown_extensions: - pymdownx.superfences: custom_fences: - name: mermaid class: mermaid format: !!python/name:pymdownx.superfences.fence_code_format ``` === "7.x" ``` yaml markdown_extensions: - pymdownx.superfences: custom_fences: - name: mermaid class: mermaid-experimental format: !!python/name:pymdownx.superfences.fence_code_format ``` [SuperFences]: setup/extensions/python-markdown-extensions.md#superfences [diagrams]: reference/diagrams.md [Mermaid.js]: https://mermaid-js.github.io/mermaid/ #### `google_analytics` This option was [deprecated in MkDocs 1.2.0], as the implementation of a JavaScript-based analytics integration is the responsibility of a theme. The following lines must be changed: === "8.x" ``` yaml extra: analytics: provider: google property: UA-XXXXXXXX-X ``` === "7.x" ``` yaml google_analytics: - UA-XXXXXXXX-X - auto ``` [deprecated in MkDocs 1.2.0]: https://www.mkdocs.org/about/release-notes/#backward-incompatible-changes-in-12 ### Changes to `*.html` files { data-search-exclude } The templates have undergone a set of changes to make them future-proof. If you've used theme extension to override a block or template, make sure that it matches the new structure: - If you've overridden a __block__, check `base.html` for potential changes - If you've overridden a __template__, check the respective `*.html` file for potential changes === ":octicons-file-code-16: `base.html`" ``` diff @@ -13,11 +13,6 @@ {% elif config.site_description %} {% endif %} - {% if page and page.meta and page.meta.keywords %} - - {% elif config.site_keywords %} - - {% endif %} {% if page and page.meta and page.meta.author %} {% elif config.site_author %} @@ -61,15 +56,13 @@ font.text | replace(' ', '+') + ':300,400,400i,700%7C' + font.code | replace(' ', '+') }}&display=fallback"> - + {% endif %} {% endblock %} - {% if config.extra.manifest %} - - {% endif %} {% for path in config["extra_css"] %} {% endfor %} + {% include "partials/javascripts/base.html" %} {% block analytics %} {% include "partials/integrations/analytics.html" %} {% endblock %} @@ -89,7 +82,6 @@ {% endif %} {% set features = config.theme.features or [] %} - {% include "partials/javascripts/base.html" %} {% if not config.theme.palette is mapping %} {% include "partials/javascripts/palette.html" %} {% endif %} @@ -106,13 +98,25 @@
{% if self.announce() %} -