mkdocs-material

[!WARNING]

Material for MkDocs is in maintenance mode

Going forward, the Material for MkDocs team focuses on Zensical, a next-gen static site generator built from first principles. We will provide critical bug fixes and security updates for Material for MkDocs until November 2026.

Read the full announcement on our blog

Changes

• Limited version range of mkdocs to <2
• Updated MkDocs 2.0 incompatibility warning (clarify relation with MkDocs)

[!WARNING]

Material for MkDocs is in maintenance mode

Going forward, the Material for MkDocs team focuses on Zensical, a next-gen static site generator built from first principles. We will provide critical bug fixes and security updates for Material for MkDocs until November 2026.

Read the full announcement on our blog

Changes

• Hardened social cards plugin by switching to sandboxed environment (recommended by @caveeroo)
• Updated MkDocs 2.0 incompatibility warning

[!WARNING]

Material for MkDocs is in maintenance mode

Going forward, the Material for MkDocs team focuses on Zensical, a next-gen static site generator built from first principles. We will provide critical bug fixes and security updates for Material for MkDocs until November 2026.

Read the full announcement on our blog

Changes

• Fixed #8567: Print MkDocs 2.0 incompatibility warning to stderr

[!WARNING]

Material for MkDocs is in maintenance mode

Going forward, the Material for MkDocs team focuses on Zensical, a next-gen static site generator built from first principles. We will provide critical bug fixes and security updates for Material for MkDocs until November 2026.

Read the full announcement on our blog

Changes

• Opened up version ranges of optional dependencies for forward-compatibility
• Added warning to mkdocs build about impending MkDocs 2.0 incompatibility (doesn't affect strict mode)

[!WARNING]

Material for MkDocs is in maintenance mode

Going forward, the Material for MkDocs team focuses on Zensical, a next-gen static site generator built from first principles. We will provide critical bug fixes and security updates for Material for MkDocs until November 2026.

Read the full announcement on our blog

Changes

• Updated requests to 2.30+ to mitigate CVE in urllib
• Fixed privacy plugin not picking up protocol-relative URLs
• Fixed #8542: false positives and negatives captured in privacy plugin

[!WARNING]

Material for MkDocs is now in maintenance mode

This is the last release of Material for MkDocs that will receive new features. Going forward, the Material for MkDocs team focuses on Zensical, a next-gen static site generator built from first principles. We will provide critical bug fixes and security updates for Material for MkDocs for 12 months at least.

Read the full announcement on our blog

This release includes all features that were previously exclusive to the Insiders edition. These features are now freely available to everyone.

Note on deprecated plugins: The projects and typeset plugins are included in this release, but must be considered deprecated. Both plugins proved unsustainable to maintain and represent architectural dead ends. They are provided as-is without ongoing support.

Changes:

• Added support for projects plugin (for compat, now deprecated)

• Added support for typeset plugin (for compat, now deprecated)

• Added support for pinned blog posts and author profiles

• Added support for customizing pagination for blog index pages

• Added support for customizing blog category sort order

• Added support for staying on page when switching languages

• Added support for disabling tags in table of contents

• Added support for nested tags and shadow tags

• Added support for footnote tooltips

• Added support for instant previews

• Added support for instant prefetching

• Added support for custom social card layouts

• Added support for custom social card background images

• Added support for selectable rangs in code blocks

• Added support for custom selectors for code annotations

• Added support for configurable log level in privacy plugin

• Added support for processing of external links in privacy plugin

• Added support for automatic image optimization via optimize plugin

• Added support for navigation paths (breadcrumbs)

• Fixed #8519: Vector accents do not render when using KaTeX

• Updated Burmese translation

• Updated Georgian translation

• Updated Serbian translations
• Fixed #8458: Temporary pin of click dependency

• Fixed #8446: Deprecation warning as of Python 3.14 in Emoji extension
• Fixed #8440: & character not escaped in search highlighting
• Fixed #8439: FontAwesome icons color not set in social cards (regression)

• Added support for Python 3.14
• Updated Bahasa Malaysia translations

• Updated Azerbaijani translations

• Fixed last compat issues with minijinja, now 100% compatible

• Fixed #8396: Videos do not autoplay when inside a content tab
• Fixed #8394: Stroke width not effective in Mermaid.js diagrams
• Fixed disappearing version selector when hiding page title

• Fixed #8349: Info plugin doesn't correctly detect virtualenv in some cases
• Fixed #8334: Find-in-page detects matches in hidden search result list

• Updated Mongolian translations
• Improved semantic markup of "edit this page" button
• Improved info plugin virtual environment resolution
• Fixed #8291: Large font size setting throws of breakpoints in JavaScript

• Fixed #8215: Social plugin crashes when CairoSVG is updated to 2.8

• Fixed #8204: Annotations showing list markers in print view
• Fixed #8153: Improve style of cardinality symbols in Mermaid.js ER diagrams

• Fixed #8158: Flip footnote back reference icon for right-to-left languages

• Updated Docker image to latest Alpine Linux
• Bump required Jinja version to 3.1
• Fixed #8133: Jinja filter items not available (9.6.10 regression)
• Fixed #8128: Search plugin not entirely disabled via enabled setting

This version is a pure refactoring release, and does not contain new features or bug fixes. It strives to improve the compatibility of our templates with alternative Jinja-like template engines that we're currently exploring, including minijinja.

Additionally, it replaces several instances of Python function invocations with idiomatic use of template filters. All instances where variables have been mutated inside templates have been replaced. Most changes have been made in partials, and only a few in blocks, and all of them are fully backward compatible, so no changes to overrides are necessary.

Note that this release does not replace the Jinja template engine with minijinja. However, our templates are now 99% compatible with minijinja, which means we can explore alternative Jinja-compatible implementations. Additionally, immutability and removal of almost all Python function invocations means much more idiomatic templating.

• Updated Serbo-Croatian translations
• Fixed #8086: Custom SVG icons containing hashes break rendering
• Fixed #8067: Drawer has gap on right side in Firefox on some OSs

• Added Welsh translations
• Fixed #8076: Privacy plugin crashes if HTTP download fails

• Fixed #8056: Error in backrefs implementation (9.6.6 regression)
• Fixed #8054: Unescaped quotes in ARIA labels of table of contents

• Fixed #8040: Privacy plugin not replacing exteral assets (9.6.5 regression)
• Fixed #8031: Replace unmaintained regex package in search plugin

• Fixed #8016: Tags listing not showing when when file name has spaces
• Fixed #8012: Privacy plugin crashes if HTTP download fails

• Fixed #7985: Blog content sometimes not stretching to full width
• Fixed #7978: Navigation rendering bug in Safari 18.3

• Fixed rendering of arrow heads in Mermaid.js class diagrams
• Fixed #7960: Tags plugin crashes on numeric metadata titles

• Fixed #7955: Excessively long words don't break on narrow screens
• Fixed #7947: Scope setting interferes with outdated version banner

• Fixed #7943: Tags plugin crashing due to merge error

• Added meta plugin
• Rewrite of the tags plugin
• Added support for allow lists in tags plugin
• Added support for and custom sorting in tags plugin
• Added support for related links in blog plugin
• Added support for custom index pages in blog plugin
• Added support for navigation subtitles
• Fixed #7924: Anchors might require two clicks when using instant navigation

• Fixed #7913: Social plugin renders attribute lists in page title

• Adjusted title color in dark mode for all supported Mermaid.js diagrams
• Fixed #7803: Privacy plugin crashes on generated files
• Fixed #7781: Mermaid.js flow chart title not visible in dark mode

• Fixed #7774: Disabling social cards doesn't work

• Fixed #7750: Numeric tags break search
• Fixed #7748: Blog plugin breaks when using future drafts (9.5.45 regression)

Thanks go to @perpil for their contributions

• Added support for removing preload hints in privacy plugin
• Fixed #7734: Code blocks in h5 headlines are uppercased
• Fixed #7725: Blog plugin crashing on missing timezone (9.5.45 regression)

Thanks go to @nejch and @perpil for their contributions

• Reduced size of Docker image through multi-stage build
• Fixed #7708: Blog plugin crashing on YAML dates with timezones

Thanks go to @FrancoisCapon and @perpil for their contributions

• Fixed #7672: Font CSS 404's when using privacy plugin (9.5.43 regression)

Thanks go to @nejch for their contributions.

• Added support for external images in SVGs in privacy plugin
• Fixed #7651: Privacy plugin doesn't handle quoted URLs in CSS

Thanks go to @nejch for their contributions

• Fixed #7625: Invalid encoding of boolean attributes in privacy plugin
• Fixed #7624: Crash when disabling privacy plugin (9.5.41 regression)

• Fixed #7619: Improved tooltip on logo disappears after instant navigation
• Fixed #7616: Race condition in built-in privacy plugin when inlining assets
• Fixed #7615: Comments and "Was this page helpful?" visible when printing

• Updated Latvian translations
• Fixed #7597: Social cards not using site name on home page

Thanks go to @pekkaklarck and @klejejs for their contributions

• Fixed #7226: not staying on page when using mike's canonical versioning

Thanks go to @ilyagr for their contributions

• Added Albanian translations

Thanks go to @gerardkraja for their contributions

• Added 4th and 5th level ordered list styles
• Fixed #7548: Tags have no spacing in search

• Fixed #7544: Social cards incorrectly rendering HTML entities
• Fixed #7542: Improved support for setting custom list styles

• Fixed #7498: Search not showing for Vietnamese language

• Updated Mermaid.js to version 11 (latest)

Thanks go to @manselmi for their contributions

• Fixed #7453: Incorrect position of tooltip when sorting table

• Fixed RXSS vulnerability via deep link in search results
• Added support for fetching latest release from GitLab

Thanks go to @joaopalmeiro for their contributions

• Fixed #7405: DockerHub missing images > 9.5.27 due to change in Alpine/APK

• Fixed #7380: Navigation icons disappearing on hover in Safari
• Fixed #7367: Blog readtime computation includes SVG text content

Thanks go to @sisp for their contributions

• Updated Galician translations
• Fixed #7362: Annotations in figure captions rendering incorrectly

Thanks go to @mmontes11 for their contributions

• Fixed #7313: Improved tooltips mounted in sidebar when feature is disabled

• Updated Estonian translations

Thanks to @Eilyre for their contributions

• Fixed #7232: Tab switches on scroll when linking tabs (9.5.19 regression)
• Fixed #7230: Blog author avatar broken when referring to local file

• Fixed #7209: Tags plugin crashing on numeric tags

• Fixed #7187: Version selector title rendering issue

• Fixed #7183: Edge case in anchor navigation when using instant navigation
• Fixed #6436: Version selector not showing version alias