Skip to content

Release notes

Upgrading

To upgrade Material to the latest version, use pip:

pip install --upgrade mkdocs-material

To inspect the currently installed version, use the following command:

pip show mkdocs-material

Material 3.x to 4.x

  • Material for MkDocs 4.x finally fixes incorrect layout on Chinese systems. The fix includes a mandatory change of the base font-size from 10px to 20px which means all rem values needed to be updated. Within the theme, px to rem calculation is now encapsulated in a new function called px2rem which is part of the SASS code base.

  • If you use Material with custom CSS that is based on rem values, note that those values must now be divided by 2. Now, 1.0rem doesn't map to 10px, but 20px. To learn more about the problem and implications, please refer to the issue in which the problem was discovered and fixed.

Material 2.x to 3.x

  • Material for MkDocs 3.x requires MkDocs 1.0 because the way paths are resolved internally changed significantly. Furthermore, pages was renamed to nav, so remember to adjust your mkdocs.yml file.

  • All extended templates should continue to work but in order to make them future-proof the url filter should be introduced on all paths. Please see the official release notes for further guidance.

Material 1.x to 2.x

  • Material for MkDocs 2.x requires MkDocs 0.17.1, as this version introduced changes to the way themes can define options. The following variables inside your project's mkdocs.yml need to be renamed:

    • extra.feature becomes theme.feature
    • extra.palette becomes theme.palette
    • extra.font becomes theme.font
    • extra.logo becomes theme.logo
  • Favicon support has been dropped by MkDocs, it must now be defined in theme.favicon (previously site_favicon).

  • Localization is now separated into theme language and search language. While there can only be a single language on theme-level, the search supports multiple languages which can be separated by commas. See the getting started guide for more guidance.

  • The search tokenizer can now be set through extra.search.tokenizer.

Changelog

4.1.0 _ March 22, 2019

  • Fixed #1023: Search for Asian languages broken after Lunr.js update
  • Fixed #1026: contenteditable elements loose focus on hotkeys

4.0.2 _ March 1, 2019

  • Fixed #1012: HTML character entities appear in search result titles

4.0.1 _ February 13, 2019

  • Fixed #762, #816: Glitch in sidebar when collapsing items
  • Fixed #869: Automatically expand details before printing

4.0.0 _ February 13, 2019

  • Added background on hover for table rows
  • Removed Google Tag Manager and reverted to Google Analytics
  • Removed blocks in partials - Jinja doesn't support them
  • Fixed #911: Chrome breaks layout if system language is Chinese [BREAKING]
  • Fixed #976: Removed FastClick

3.3.0 _ January 29, 2019

  • Moved Google Analytics integration into head using Google Tag Manager
  • Fixed #972: Unicode slugifier breaks table of contents blur on scroll
  • Fixed #974: Additional links in table of contents break blur on scroll

3.2.0 _ December 28, 2018

  • Added support for redirects using metadata refresh
  • Fixed #921: Load Google Analytics snippet asynchronously

3.1.0 _ November 17, 2018

  • Added support for Progressive Web App Manifest
  • Fixed #915: Search bug in Safari (upgraded Lunr.js)

3.0.6 _ October 26, 2018

  • Added Taiwanese translations
  • Fixed #906: JavaScript code blocks evaluated in search results

3.0.5 _ October 23, 2018

  • Added Croatian and Indonesian translations
  • Fixed #899: Skip-to-content link invalid from 2nd level on
  • Fixed #902: Missing URL filter in footer for FontAwesome link

3.0.4 _ September 3, 2018

  • Updated Dutch translations
  • Fixed #856: Removed preconnect meta tag if Google Fonts are disabled

3.0.3 _ August 7, 2018

  • Fixed #841: Additional path levels for extra CSS and JS

3.0.2 _ August 6, 2018

  • Fixed #839: Lunr.js stemmer imports incorrect

3.0.1 _ August 5, 2018

  • Fixed #838: Search result links incorrect

3.0.0 _ August 5, 2018

  • Upgraded MkDocs to 1.0 [BREAKING]
  • Upgraded Python in official Docker image to 3.6
  • Added Serbian and Serbo-Croatian translations

2.9.4 _ July 29, 2018

  • Fixed build error after MkDocs upgrade

2.9.3 _ July 29, 2018

  • Added link to home for logo in drawer
  • Fixed dependency problems between MkDocs and Tornado

2.9.2 _ June 29, 2018

  • Added Hindi and Czech translations

2.9.1 _ June 18, 2018

  • Added support for different spellings for theme color
  • Fixed #799: Added support for web font minification in production
  • Fixed #800: Added .highlighttable as an alias for .codehilitetable

2.9.0 _ June 13, 2018

  • Added support for theme color on Android
  • Fixed #796: Rendering of nested tabbed code blocks

2.8.0 _ June 10, 2018

  • Added support for grouping code blocks with tabs
  • Added Material and FontAwesome icon fonts to distribution files (GDPR)
  • Added note on compliance with GDPR
  • Added Slovak translations
  • Fixed #790: Prefixed id attributes with __ to avoid name clashes

2.7.3 _ April 26, 2018

  • Added Finnish translations

2.7.2 _ April 9, 2018

  • Fixed rendering issue for details on Edge

2.7.1 _ March 21, 2018

  • Added Galician translations
  • Fixed #730: Scroll chasing error on home page if Disqus is enabled
  • Fixed #736: Reset drawer and search upon back button invocation

2.7.0 _ March 6, 2018

  • Added ability to set absolute URL for logo
  • Added Hebrew translations

2.6.6 _ February 22, 2018

  • Added preconnect for Google Fonts for faster loading
  • Fixed #710: With tabs sidebar disappears if JavaScript is not available

2.6.5 _ February 22, 2018

  • Reverted --dev-addr flag removal from Dockerfile

2.6.4 _ February 21, 2018

  • Added Catalan translations
  • Fixed incorrect margins for buttons in Firefox and Safari
  • Replaced package manager yarn with npm 5.6
  • Reverted GitHub stars rounding method
  • Removed --dev-addr flag from Dockerfile for Windows compatibility

2.6.3 _ February 18, 2018

  • Added Vietnamese translations

2.6.2 _ February 12, 2018

  • Added Arabic translations
  • Fixed incorrect rounding of amount of GitHub stars
  • Fixed double-layered borders for tables

2.6.1 _ February 11, 2018

  • Added ability to override Disqus integration using metadata
  • Fixed #690: Duplicate slashes in source file URLs
  • Fixed #696: Active page highlight not working with default palette
  • Adjusted German translations

2.6.0 _ February 2, 2018

  • Moved default search configuration to default translation (English)
  • Added support to automatically set text direction from translation
  • Added support to disable search stop word filter in translation
  • Added support to disable search trimmer in translation
  • Added Persian translations
  • Fixed support for Polish search
  • Fixed disappearing GitHub, GitLab and Bitbucket repository icons

2.5.5 _ January 31, 2018

  • Added Hungarian translations

2.5.4 _ January 29, 2018

  • Fixed #683: gh-deploy fails inside Docker

2.5.3 _ January 25, 2018

  • Added Ukrainian translations

2.5.2 _ January 22, 2018

  • Added default search language mappings for all localizations
  • Fixed #673: Error loading non-existent search language
  • Fixed #675: Uncaught reference error when search plugin disabled

2.5.1 _ January 20, 2018

  • Fixed permalink for main headline
  • Improved missing translation handling with English as a fallback
  • Improved accessibility with skip-to-content link

2.5.0 _ January 13, 2018

  • Added support for right-to-left languages

2.4.0 _ January 11, 2018

  • Added focus state for clipboard buttons
  • Fixed #400: Search bar steals tab focus
  • Fixed search not closing on Enter when result is selected
  • Fixed search not closing when losing focus due to Tab
  • Fixed collapsed navigation links getting focus
  • Fixed outline being cut off on Tab focus of navigation links
  • Fixed bug with first search result navigation being ignored
  • Removed search result navigation via Tab (use Up and Down)
  • Removed outline resets for links
  • Improved general tabbing behavior on desktop

2.3.0 _ January 9, 2018

  • Added example (synonym: snippet) style for Admonition
  • Added synonym abstract for summary style for Admonition

2.2.6 _ December 27, 2017

  • Added Turkish translations
  • Fixed unclickable area below header in case JavaScript is not available

2.2.5 _ December 18, 2017

  • Fixed #639: Broken default favicon

2.2.4 _ December 18, 2017

  • Fixed #638: Build breaks with Jinja < 2.9

2.2.3 _ December 13, 2017

  • Fixed #630: Admonition sets padding on any last child
  • Adjusted Chinese (Traditional) translations

2.2.2 _ December 8, 2017

  • Added Dutch translations
  • Adjusted targeted link and footnote offsets
  • Simplified Admonition styles and fixed padding bug

2.2.1 _ December 2, 2017

  • Fixed #616: Minor styling error with title-only admonition blocks
  • Removed border for table of contents and improved spacing

2.2.0 _ November 22, 2017

  • Added support for hero teaser
  • Added Portuguese translations
  • Fixed #586: Footnote backref target offset regression
  • Fixed #605: Search stemmers not correctly loaded

2.1.1 _ November 21, 2017

  • Replaced deprecated babel-preset-es2015 with babel-preset-env
  • Refactored Gulp build pipeline with Webpack
  • Removed right border on sidebars
  • Fixed broken color transition on header

2.1.0 _ November 19, 2017

  • Added support for white as a primary color
  • Added support for sliding site name and title
  • Fixed redundant clipboard button when using line numbers on code blocks
  • Improved header appearance by making it taller
  • Improved tabs appearance
  • Improved CSS customizability by leveraging inheritance
  • Removed scroll shadows via background-attachment

2.0.4 _ November 5, 2017

  • Fixed details not opening with footnote reference

2.0.3 _ November 5, 2017

  • Added Japanese translations
  • Fixed #540: Jumping to anchor inside details doesn't open it
  • Fixed active link colors in footer

2.0.2 _ November 1, 2017

  • Added Russian translations
  • Fixed #542: Horizontal scrollbar between 1220px and 1234px
  • Fixed #553: Metadata values only rendering first character
  • Fixed #558: Flash of unstyled content
  • Fixed favicon regression caused by deprecation upstream

2.0.1 _ October 31, 2017

  • Fixed error when initializing search
  • Fixed styles for link to edit the current page
  • Fixed styles on nested admonition in details

2.0.0 _ October 31, 2017

  • Added support for MkDocs 0.17.1 theme configuration options
  • Added support for easier configuration of search tokenizer
  • Added support to disable search
  • Added Korean translations
  • Removed support for MkDocs 0.16.x [BREAKING]

1.12.2 _ October 26, 2017

  • Added Italian, Norwegian, French and Chinese translations

1.12.1 _ October 22, 2017

  • Added Polish, Swedish and Spanish translations
  • Improved downward compatibility with custom partials
  • Temporarily pinned MkDocs version within Docker image to 0.16.3
  • Fixed #519: Missing theme configuration file

1.12.0 _ October 20, 2017

  • Added support for setting language(s) via mkdocs.yml
  • Added support for default localization
  • Added German and Danish translations
  • Fixed #374: Search bar misalignment on big screens

1.11.0 _ October 19, 2017

  • Added localization to clipboard
  • Refactored localization logic

1.10.4 _ October 18, 2017

  • Improved print styles of code blocks
  • Improved search UX (don't close on enter if no selection)
  • Fixed #495: Vertical scrollbar on short pages

1.10.3 _ October 11, 2017

  • Fixed #484: Vertical scrollbar on some MathJax formulas
  • Fixed #483: Footnote backref target offset regression

1.10.2 _ October 6, 2017

  • Fixed #468: Sidebar shows scrollbar if content is shorter (in Safari)

1.10.1 _ September 14, 2017

  • Fixed #455: Bold code blocks rendered with normal font weight

1.10.0 _ September 1, 2017

  • Added support to make logo default icon configurable
  • Fixed uninitialized overflow scrolling on main pane for iOS
  • Fixed error in mobile navigation in case JavaScript is not available
  • Fixed incorrect color transition for nested panes in mobile navigation
  • Improved checkbox styles for Tasklist from PyMdown Extension package

1.9.0 _ August 29, 2017

  • Added info (synonym: todo) style for Admonition
  • Added question (synonym: help, faq) style for Admonition
  • Added support for Details from PyMdown Extensions package
  • Improved Admonition styles to match Details
  • Improved styles for social links in footer
  • Replaced ligatures with Unicode code points to avoid broken layout
  • Upgraded PyMdown Extensions package dependency to >= 3.4

1.8.1 _ August 7, 2017

  • Fixed #421: Missing pagination for GitHub API

1.8.0 _ August 2, 2017

  • Added support for lazy-loading of search results for better performance
  • Added support for customization of search tokenizer/separator
  • Fixed #424: Search doesn't handle capital letters anymore
  • Fixed #419: Search doesn't work on whole words

1.7.5 _ July 25, 2017

  • Fixed #398: Forms broken due to search shortcuts
  • Improved search overall user experience
  • Improved search matching and highlighting
  • Improved search accessibility

1.7.4 _ June 21, 2017

  • Fixed functional link colors in table of contents for active palette
  • Fixed #368: Compatibility issues with IE11

1.7.3 _ June 7, 2017

  • Fixed error when setting language to Japanese for site search

1.7.2 _ June 6, 2017

  • Fixed offset of search box when repo_url is not set
  • Fixed non-disappearing tooltip

1.7.1 _ June 1, 2017

  • Fixed wrong z-index order of header, overlay and drawer
  • Fixed wrong offset of targeted footnote back references

1.7.0 _ June 1, 2017

  • Added "copy to clipboard" buttons to code blocks
  • Added support for multilingual site search
  • Fixed search term highlighting for non-latin languages

1.6.4 _ May 24, 2017

  • Fixed #337: JavaScript error for GitHub organization URLs

1.6.3 _ May 16, 2017

  • Fixed #329: Broken source stats for private or unknown GitHub repos

1.6.2 _ May 15, 2017

  • Fixed #316: Fatal error for git clone on Windows
  • Fixed #320: Chrome 58 creates double underline for abbr tags
  • Fixed #323: Ligatures rendered inside code blocks
  • Fixed miscalculated sidebar height due to missing margin collapse
  • Changed deprecated MathJax CDN to Cloudflare

1.6.1 _ April 23, 2017

  • Fixed following of active/focused element if search input is focused
  • Fixed layer order of search component elements

1.6.0 _ April 22, 2017

  • Added build test for Docker image on Travis
  • Added search overlay for better user experience (focus)
  • Added language from localizations to html tag
  • Fixed #270: source links broken for absolute URLs
  • Fixed missing top spacing for first targeted element in content
  • Fixed too small footnote divider when using larger font sizes

1.5.5 _ April 20, 2017

  • Fixed #282: Browser search (Meta+F) is hijacked

1.5.4 _ April 8, 2017

  • Fixed broken highlighting for two or more search terms
  • Fixed missing search results when only a h1 is present
  • Fixed unresponsive overlay on Android

1.5.3 _ April 7, 2017

  • Fixed deprecated calls for template variables
  • Fixed wrong palette color for focused search result
  • Fixed JavaScript errors on 404 page
  • Fixed missing top spacing on 404 page
  • Fixed missing right spacing on overflow of source container

1.5.2 _ April 5, 2017

  • Added requirements as explicit dependencies in setup.py
  • Fixed non-synchronized transitions in search form

1.5.1 _ March 30, 2017

  • Fixed rendering and offset of targetted footnotes
  • Fixed #238: Link on logo is not set to site_url

1.5.0 _ March 24, 2017

  • Added support for localization of search placeholder
  • Added keyboard events for quick access of search
  • Added keyboard events for search control
  • Added opacity on hover for search buttons
  • Added git hook to skip CI build on non-src changes
  • Fixed non-resetting search placeholder when input is cleared
  • Fixed error for unescaped parentheses in search term
  • Fixed #229: Button to clear search missing
  • Fixed #231: Escape key doesn't exit search
  • Removed old-style figures from font feature settings

1.4.1 _ March 16, 2017

  • Fixed invalid destructuring attempt on NodeList (in Safari, Edge, IE)

1.4.0 _ March 16, 2017

  • Added support for grouping searched sections by documents
  • Added support for highlighting of search terms
  • Added support for localization of search results
  • Fixed #216: table of contents icon doesn't show if h1 is not present
  • Reworked style and layout of search results for better usability

1.3.0 _ March 11, 2017

  • Added support for page-specific title and description using metadata
  • Added support for linking source files to documentation
  • Fixed jitter and offset of sidebar when zooming browser
  • Fixed incorrectly initialized tablet sidebar height
  • Fixed regression for #1: GitHub stars break if repo_url ends with a /
  • Fixed undesired white line below copyright footer due to base font scaling
  • Fixed issue with whitespace in path for scripts
  • Fixed #205: support non-fixed (static) header
  • Refactored footnote references for better visibility
  • Reduced repaints to a minimum for non-tabs configuration
  • Reduced contrast of edit button (slightly)

1.2.0 _ March 3, 2017

  • Added quote (synonym: cite) style for Admonition
  • Added help message to build pipeline
  • Fixed wrong navigation link colors when applying palette
  • Fixed #197: Link missing in tabs navigation on deeply nested items
  • Removed unnecessary dev dependencies

1.1.1 _ February 26, 2017

  • Fixed incorrectly displayed nested lists when using tabs

1.1.0 _ February 26, 2017

  • Added tabs navigation feature (optional)
  • Added Disqus integration (optional)
  • Added a high resolution Favicon with the new logo
  • Added static type checking using Facebook's Flow
  • Fixed #173: Dictionary elements have no bottom spacing
  • Fixed #175: Tables cannot be set to 100% width
  • Fixed race conditions in build related to asset revisioning
  • Fixed accidentally re-introduced Permalink on top-level headline
  • Fixed alignment of logo in drawer on IE11
  • Refactored styles related to tables
  • Refactored and automated Docker build and PyPI release
  • Refactored build scripts

1.0.5 _ February 18, 2017

  • Fixed #153: Sidebar flows out of constrained area in Chrome 56
  • Fixed #159: Footer jitter due to JavaScript if content is short

1.0.4 _ February 16, 2017

  • Fixed #142: Documentation build errors if h1 is defined as raw HTML
  • Fixed #164: PyPI release does not build and install
  • Fixed offsets of targeted headlines
  • Increased sidebar font size by 0.12rem

1.0.3 _ January 22, 2017

  • Fixed #117: Table of contents items don't blur on fast scrolling
  • Refactored sidebar positioning logic
  • Further reduction of repaints

1.0.2 _ January 15, 2017

  • Fixed #108: Horizontal scrollbar in content area

1.0.1 _ January 14, 2017

  • Fixed massive repaints happening when scrolling
  • Fixed footer back reference positions in case of overflow
  • Fixed header logo from showing when the menu icon is rendered
  • Changed scrollbar behavior to only show when content overflows

1.0.0 _ January 13, 2017

  • Introduced Webpack for more sophisticated JavaScript bundling
  • Introduced ESLint and Stylelint for code style checks
  • Introduced more accurate Material Design colors and shadows
  • Introduced modular scales for harmonic font sizing
  • Introduced git-hooks for better development workflow
  • Rewrite of CSS using the BEM methodology and SassDoc guidelines
  • Rewrite of JavaScript using ES6 and Babel as a transpiler
  • Rewrite of Admonition, Permalinks and CodeHilite integration
  • Rewrite of the complete typographical system
  • Rewrite of Gulp asset pipeline in ES6 and separation of tasks
  • Removed Bower as a dependency in favor of NPM
  • Removed custom icon build in favor of the Material Design iconset
  • Removed _blank targets on links due to vulnerability: http://bit.ly/1Mk2Rtw
  • Removed unversioned assets from build directory
  • Restructured templates into base templates and partials
  • Added build and watch scripts in package.json
  • Added support for Metadata and Footnotes Markdown extensions
  • Added support for PyMdown Extensions package
  • Added support for collapsible sections in navigation
  • Added support for separate table of contents
  • Added support for better accessibility through REM-based layout
  • Added icons for GitHub, GitLab and BitBucket integrations
  • Added more detailed documentation on specimen, extensions etc.
  • Added a 404.html error page for deployment on GitHub Pages
  • Fixed live reload chain in watch mode when saving a template
  • Fixed variable references to work with MkDocs 0.16

0.2.4 _ June 26, 2016

  • Fixed improperly set default favicon
  • Fixed #33: Protocol relative URL for webfonts doesn't work with file://
  • Fixed #34: IE11 on Windows 7 doesn't honor max-width on main tag
  • Fixed #35: Add styling for blockquotes

0.2.3 _ May 16, 2016

  • Fixed #25: Highlight inline fenced blocks
  • Fixed #26: Better highlighting for keystrokes
  • Fixed #30: Suboptimal syntax highlighting for PHP

0.2.2 _ March 20, 2016

  • Fixed #15: Document Pygments dependency for CodeHilite
  • Fixed #16: Favicon could not be set through mkdocs.yml
  • Fixed #17: Put version into own container for styling
  • Fixed #20: Fix rounded borders for tables

0.2.1 _ March 12, 2016

  • Fixed #10: Invisible header after closing search bar with ESC key
  • Fixed #13: Table cells don't wrap
  • Fixed empty list in table of contents when no headline is defined
  • Corrected wrong path for static asset monitoring in Gulpfile.js
  • Set up tracking of site search for Google Analytics

0.2.0 _ February 24, 2016

  • Fixed #6: Include multiple color palettes via mkdocs.yml
  • Fixed #7: Better colors for links inside admonition notes and warnings
  • Fixed #9: Text for prev/next footer navigation should be customizable
  • Refactored templates (replaced if/else with modifiers where possible)

0.1.3 _ February 21, 2016

  • Fixed #3: Ordered lists within an unordered list have ::before content
  • Fixed #4: Click on Logo/Title without Github-Repository: "None"
  • Fixed #5: Page without headlines renders empty list in table of contents
  • Moved Modernizr to top to ensure basic usability in IE8

0.1.2 _ February 16, 2016

  • Fixed styles for deep navigational hierarchies
  • Fixed webfont delivery problem when hosted in subdirectories
  • Fixed print styles in mobile/tablet configuration
  • Added option to configure fonts in mkdocs.yml with fallbacks
  • Changed styles for admonition notes and warnings
  • Set download link to latest version if available
  • Set up tracking of outgoing links and actions for Google Analytics

0.1.1 _ February 11, 2016

  • Fixed #1: GitHub stars don't work if the repo_url ends with a /
  • Updated NPM and Bower dependencies to most recent versions
  • Changed footer/copyright link to Material theme to GitHub pages
  • Made MkDocs building/serving in build process optional
  • Set up continuous integration with Travis

0.1.0 _ February 9, 2016

  • Initial release