A Material Design theme for MkDocs

Overview

Material for MkDocs

A Material Design theme for MkDocs

Build Downloads Chat on Gitter Python Package Index Docker Pulls

Create a branded static site from a set of Markdown files to host the documentation of your Open Source or commercial project – customizable, searchable, mobile-friendly, 40+ languages. Set up in 5 minutes.

A demo is worth a thousand words — check it out at squidfunk.github.io/mkdocs-material.

Features

  • It's just Markdown — write your technical documentation in plain Markdown – no need to know HTML, JavaScript, or CSS. Material for MkDocs will do the heavy lifting and convert your writing to a beautiful and functional website.

  • Responsive by design — built from the ground up to work on all sorts of devices – from mobile phones to widescreens. The underlying fluid layout will always adapt perfectly to the available screen space.

  • Static, yet searchable — almost magically, your technical documentation website will be searchable without any further ado. Material for MkDocs comes with built-in search – no server needed – that will instantly answer your users' queries.

  • Many configuration options — change the color palette, font families, language, icons, favicon and logo. Add a source repository link, links to your social profiles, Google Analytics and Disqus - all with a few lines of code.

  • Truly international — thanks to many contributors, Material for MkDocs includes translations for more than 40 languages and offers full native RTL (right-to-left) support for languages such as Arabic, Persian (Farsi) and Hebrew.

  • Accessible — Material for MkDocs provides extensible keyboard navigation and semantic markup including role attributes and landmarks. Furthermore, the layout is entirely based on rem values, respecting the user's default font size.

  • Beyond GitHub Markdown — integrates natively with Python Markdown Extensions, offering additional elements like callouts, tabbed content containers, mathematical formulas, critic markup, task lists, and emojis.

  • Modern architecture — Material for MkDocs's underlying codebase is built with TypeScript, RxJS, and SCSS, and is compiled with Webpack, bringing excellent possibilities for theme extension and customization.

Material for MkDocs uses the sponsorware release strategy, which means that new features are first exclusively released to sponsors as part of Material for MkDocs Insiders. Read on to learn how sponsorship works, and how you can become a sponsor.

Quick start

Material for MkDocs can be installed with pip:

pip install mkdocs-material

Add the following line to mkdocs.yml:

theme:
  name: material

For other installation methods, configuration options, and a demo, visit squidfunk.github.io/mkdocs-material

Premium Sponsors

Users

License

MIT License

Copyright (c) 2016-2020 Martin Donath

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Comments
  • 🚀 Material for MkDocs 5.0.0 RC 4

    🚀 Material for MkDocs 5.0.0 RC 4

    Help test Material 5 RC 4! Deploy preview

    Please post any problems you encounter during migration in this issue.

    Installation

    Using pip:

    pip install "mkdocs-material>=5.0.0rc4"
    

    Using docker:

    docker pull squidfunk/mkdocs-material:5.0.0rc4
    

    Features

    • [x] Reactive architecture – try __material.dialog$.next("Hi!") in the console!
    • [x] Instant loading – make Material behave like a Single Page Application!
    • [x] Improved CSS customization with CSS variables – define your CI colors!
    • [x] Improved CSS resilience, e.g. proper sidebar locking for customized headers
    • [x] Improved icon integration and configuration – now including over 5k icons!
    • [x] Added possibility to use any icon for logo, repository and social links
    • [x] Search UI does not freeze anymore (moved to web worker)
    • [x] Search index built only once when using instant loading
    • [x] Improved extensible keyboard handling
    • [x] Support for prebuilt search indexes
    • [x] Support for displaying stars and forks for GitLab repositories
    • [x] Support for scroll snapping of sidebars and search results
    • [x] Reduced HTML and CSS footprint due to deprecation of Internet Explorer support
    • [x] Slight facelifting of some UI elements (Admonitions, tables, ...)

    Fixed in RC 2

    • [x] #1505: Search does not close – c0abaf5
    • [x] #1503: Exception when setting only logo icon – fcbd47c
    • [x] #1502: Tabbed content alignment – 4d386df, 447d409
    • [x] #1499, #1501: Code block styling issues with pymdownx.inline and inline

    Fixed in RC 3

    • [x] #1515: Return link of footnote not show after convert to pdf enhancement
    • [x] Fixed Admonitions for print media
    • [x] Fixed Details for Safari (iOS and macOS)
    • [x] Fixed hover states for nested items in mobile navigation
    • [x] Improved rendering performance
    • [x] Improved social icons and copyright notice alignment
    • [x] Improved accessibility

    Fixed in RC 4

    • [x] Fixed #1544: Move logo into partial for easier overriding enhancement – c9b2c1e
    • [x] Fixed #1518: Allow configuration of default search query pre-processing function enhancement – 64caf62
    • [x] Fixed #1507: Instant loading scroll restoration bug – 4d370fe
    • [x] Fixed #1451: Nested PDFs and SVGs seem to be ignored as page content bug – 42524ae1
    • [x] Fixed replacement of skip link and announcement bar on instant load – 908d34b8
    • [x] Fixed bug where a popstate event triggered history.pushState again
    • [x] Fixed header ellipsis when title equals site name
    • [x] Fixed hover states of search input for black and white palette
    • [x] Removed required attribute on search input
    • [x] Improved global keyboard events to only emit when not in editable element
    • [x] Improved color customization of details arrow icon
    • [x] Improved copy-to-clipboard button sizing in Admonitions

    Migration

    See the migration guide in the deploy preview.

    opened by squidfunk 190
  • Material 5.0.0 Status

    Material 5.0.0 Status

    TL;DR This issue is meant for updates and discussions on the progress of the rework of the theme. Please feel free to checkout and try the refactor/rxjs-typescript branch and comment on the current state of development.

    Description

    The last major releases of Material for MkDocs were mainly issued for compatibility reasons. While version 2 and 3 were related to backward incompatible changes of MkDocs (0.17.1 and 1.0 respectively), version 4 was released due to backward incompatible changes related to users with Chinese system languages (#911). The next iteration, version 5, is a substantial rewrite of the underlying JavaScript functionality to a TypeScript and RxJS-based architecture. This will yield the following major benefits:

    1. All features that are provided by the theme (e.g. the sidebars, tabs, search, etc.) will be observable by 3rd party JavaScript. This allows for very easy extension and customization. This will address issues like #1102 where users want to extend the functionality of the theme without re-compiling or forking it. Also, disabling functionality should be easier.

    2. Improving search performance. Search will be moved to a web worker and exhibit better caching and re-building behavior. This will mitigate problems were the UI freezes due to large search indexes which pre-building on the server-side only partly solves. Furthermore, search will be re-architected to fit into the plugin concept introduced by MkDocs 1.x.

    3. Color customization will be re-implemented using CSS variables. Changing the color to your custom brand colors will be even simpler and the theme will become smaller (as the palette CSS file will not be necessary anymore). Support for CSS variables is pretty great by now, but there are some browsers that don't support it, respectively IE 11, Opera mini, QQ browser and Baidu browser. These browsers will receive a (probably neutral) fallback color. If you must support those browsers, you can still extend the theme and customize the build will custom CSS colors as already described in the customization guide.

    There might also be some slight face lifting, but the main aspects of Material 5 is the introduction of a more modern architecture. The rewrite will also make the theme testable, so unit tests can and will be written to ensure functionality.

    I will document my progress here and there will be a beta phase similar to before the release of 1.0.0 (#46). Some lists with things that need to be done will follow.

    Evaluate

    • [x] ~Consider flexsearch as an alternative to lunr.js~

    TODOs

    5.0

    General

    • [x] Move everything except JavaScript compilation out of Webpack into Makefile
    • [x] Rewrite Webpack configuration in TypeScript
    • [x] Setup TypeScript project structure
    • [x] Implement experimental instant loading
    • [x] Add a plugin section to the docs
    • [x] Rewrite all components to new architecture
    • [x] Check browser support before release

    Functionality

    General
    • [x] Polyfill <details>/<summary> functionality
    • [x] Wrap all data tables for better overflow scrolling
    • [x] Automatically open <details> after child-anchor jump
    • [x] Automatically open <details> before printing
    • [x] Automatically close drawer on anchor jump
    • [x] General keyboard handlers
    • [x] Clipboard.js integration
    • [x] Cleanup code block CSS
    Scroll-related
    • [x] Toggle header shadow on scroll
    • [x] Toggle header title swap on scroll
    • [x] Toggle hero visibility on scroll
    • [x] Toggle tabs visibility on scroll
    Sidebars
    • [x] Position sidebar with navigation
    • [x] Position sidebar with table of contents
    • [x] Blur links in table of contents
    • [x] Apply scrollfix for active navigation for iOS
    • [x] Collapse/expand nested navigation
    Search
    • [x] Move search into web worker (currently w/o fallback, do we need one?)
    • [ ] ~~Persist search index in local storage~~ see https://github.com/squidfunk/mkdocs-material/issues/1465#issuecomment-588286846
    • [ ] ~~Compress search index~~ see https://github.com/squidfunk/mkdocs-material/issues/1465#issuecomment-588286846
    • [x] Focus input after form reset
    • [x] Focus input after opening search
    • [x] Focus query if search is open and character is typed
    • [x] Add (multi-)language support
    • [x] Search keyboard handlers
    • [x] Fix margin / spacing of search bar if no source repository is given
    • [x] Lock body for active search on mobile
    Accessibility
    • [x] Handle tabbing context for better accessibility
    • [x] Reset tabbing behavior
    Repository
    • [x] Make repository icon configurable
    • [x] Retrieve facts for the given repository
    • [x] Render repository information

    Issues

    • [x] Add 'selected' as toc item state (#1102)
    • [x] Update Font Awesome to LATEST (#756)
    • [x] Fix rendering issues in table of contents (#1292)
    • [x] Fixed meta title and description only rendering first character bug (#1324)
    • [x] Add announcement bar (#1190)
    • [x] Update Material icons to LATEST (#1174)
    • [x] Add missing background-color definition on root (#1418)
    • [x] Fix error on clipboard in combination with superfences (#1440)
    • [x] Refactor color customization to use CSS variables (#1297)
    • [x] Fix navigation CTRL-click issues (#1177)
    • [x] Decide on main footer block (#1351)

    5.x

    • [ ] Add dark mode (#1305)
    • [ ] Add dark mode automatism via prefers-color-scheme (#1266)
    proposal 
    opened by squidfunk 84
  • Status of 1.0.0

    Status of 1.0.0

    This issue is meant for updates and discussions on the progress of the rework of the theme. Please feel free to checkout and try the rework branch and comment on the current state of development.

    1.0.0-beta

    • [x] Implement search modal
    • [x] Refactor JavaScript
    • [x] Integrate Google Analytics from 0.2.x
    • [x] Integrate palettes from 0.2.x
    • [x] Refactor table styles from 0.2.x
    • [x] Create specimen page and check for missing styles
    • [x] Add preventDefault on overlay for iOS when menu is open
    • [x] Refactor search result code in SCSS

    1.0.0-rc

    • [x] Put path into header (breadcrumbs)
    • [x] Constrain image width to content area (like in 0.2.4)
    • [x] Account for height change after parsing MathJax
    • [x] Fix bug with non-stretching container when there is no content
    • [x] Refactor footer to be variable-size for arbitrary footer content
    • [x] Refactor link in footer (together with social icons)
    • [x] Include social icons in footer (see #49)
    • [x] Check all issues in original Material theme and ensure they are fixed in rework
    • [x] Full integration with pymdown extensions
    • [x] Write documentation on pymdown extensions
    • [x] Fix anchor offsets for blurring
    • [x] Add -webkit-overflow-scrolling via JavaScript on navigation
    • [x] Add "Edit on GitHub" Link (dependent on mkdocs 0.16 release)
    • [x] Make logo/icon configurable (webfont, svg)

    1.0.0

    • [x] Rewrite getting started guide
    • [x] Write documentation on theme extension and customization
    • [x] Write documentation on how to integrate theme from GitHub
    • [x] Write CONTRIBUTING.md

    1.0.x

    • [x] Switch to PR-based development workflow after big merge
    • [ ] Write unit tests with karma for components
    • [ ] Refactor search algorithm
    • [ ] Add a separate homepage/langing page layout
    • [ ] Refactor 404 template
    • [ ] Fix missing repaint on header/nav for tablet breakpoint

    DONE

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

    Testing

    The easiest way to test the rework branch is by downloading or cloning it into your project's root and using the theme_dir key in your mkdocs.yml to refer to the theme:

    1. cd your_project
    2. git clone https://github.com/squidfunk/mkdocs-material
    3. git checkout rework
    4. cd ..

    In your mkdocs.yml add:

    theme_dir: mkdocs-material/material
    
    proposal 
    opened by squidfunk 70
  • 🚀 Material for MkDocs 8 – Beta

    🚀 Material for MkDocs 8 – Beta

    With the help of my awesome sponsors, I'm happy to announce that the 'Ghost Pepper' funding goal has been reached, which means that code annotations, anchor tracking and versioning warnings are finding their way into this repository!

    Since those are some pretty nifty features, it's a good time to wrap them up into a new major release and drop some long-standing deprecated features. This issue will track the progress on the road from the beta to the final release of version 8.

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

    Installation

    pip install mkdocs-material==8.0.0b2
    

    Note that this is a beta release.

    Changes

    Added

    Improved

    • Content partials: there's now a new partial, which allows fpr customizing the appearance of the Markdown content without overriding base.html. This makes it easy to add a further button to the top of a page or to add arbitrary content to the footer of a page:

      {% block content %}
        {% include "partials/content.html" %}
      {% endblock %}
      
    • Copyright partial: the copyright has been moved into a separate partial, which lifts the need to override the footer.html template when changing the copyright information.

      <div class="md-footer-meta md-typeset">
        <div class="md-footer-meta__inner md-grid">
          {% include "partials/copyright.html" %}
      
          <!-- Social links -->
          {% if config.extra.social %}
            {% include "partials/social.html" %}
          {% endif %}
        </div>
      </div>
      
    • Details: the open/closed state of details elements is now preserved when exiting print mode. Prior, details elements were always opened and left open when exiting print mode. Now, they will always return to their prior state.

    • Fonts: The CSS variables for fonts which are set via mkdocs.yml have been renamed, and are amended with fallback fonts by the theme, so they can be set on arbitrary elements. Before, the fallback fonts had to be copied in order to override fonts on a nested element.

    Removed

    • ~~Tabbed (legacy)~~: from version 8, only the alternate_styleof the Tabbed extension is supported, and thus mandatory. The alternate implementation is superior in many ways, and there's no reason for us to keep the legacy implementation, as it just blows up the size of the CSS.

    • ~~Disqus~~: sadly, Disqus free version has become so horrible with advertisements before and after the comment section, which is why I don't want to endorse its usage anymore. Disqus was added at a point in time where its free version was pretty good. This is not the case anymore. However, there's a new page-footer.html partial that makes it pretty easy to add it back through customization. The new comment system guide still uses Disqus as an example for a custom integration until we found a new, better provider. Suggestions welcome.

    • ~~extra.manifest~~: the web app manifest configuration setting was removed because it is essentially just a single meta tag that links to a file that must be provided by the author. Use theme extension and add it to extrahead.

    • ~~extracopyright~~: the extracopyright variable allows to set a variable via customization that was added after the copyright information. Since the copyright information is now encapsulated in a separate partial, overriding the partial is more flexible. We don't want to provide redundant ways of achieving the same thing.

    • ~~seealso~~: the seealso qualifier was originally adapted from the readthedocs theme, in order to make it easier for authors to migrate to Material for MkDocs. However, when the title is omitted, the admonition extension will render it as Seealso, which is incorrect English.

    • ~~site_keywords~~: this was added in a PR and I failed to check if this was actually supported by MkDocs. It isn't. In fact, MkDocs will print a warning that this is an unsupported setting. For this reason, we'll remove it because it only leads to confusion.

    • ~~prebuild_index~~: previously deprecated, support was now removed. See linked issue (bottom).

    TODO

    • [x] Fix positioning issues for code annotations
    • [x] Skip empty p elements before code annotation list
    • [x] Close code annotation when bubble is clicked again
    • [x] Update documentation for Tabbed
    • [x] Update documentation for adding back Disqus via customization
    • [x] Update upgrade guide

    • #3218
    • #3145
    • #2976
    • #2475
    opened by squidfunk 61
  • 🎉 Material 5 Beta 3

    🎉 Material 5 Beta 3

    Material 5 Beta 3 is here! See deploy preview.

    This will be the last beta before the first RC. The API can be considered stable, so from this beta on no big changes should be expected to the HTML or CSS.

    Please post any problems you encounter during migration in this issue.

    Installation

    pip install "mkdocs-material>=5.0.0b3"
    

    Features

    • [x] Reactive architecture – try __material.dialog$.next("Hi!") in the console!
    • [x] Instant loading – make Material behave like a Single Page Application!
    • [x] Improved CSS customization with CSS variables – define your CI colors!
    • [x] Improved CSS resilience, e.g. proper sidebar locking for customized headers
    • [x] Improved icon integration and configuration – now including over 5k icons!
    • [x] Added possibility to use any icon for logo, repository and social links
    • [x] Search UI does not freeze anymore (moved to web worker)
    • [x] Search index built only once when using instant loading
    • [x] Improved extensible keyboard handling
    • [x] Support for prebuilt search indexes
    • [x] Support for displaying stars and forks for GitLab repositories
    • [x] Support for scroll snapping of sidebars and search results
    • [x] Reduced HTML and CSS footprint due to deprecation of Internet Explorer support
    • [x] Slight facelifting of some UI elements (Admonitions, tables, ...)

    Migration

    Material 5 includes some long awaited but breaking changes. The migration guide will help you switch to the latest version.

    Changes to mkdocs.yml

    Following is a list of changes that need to be made to your mkdocs.yml. Note that you only need to adjust the values if you defined them. Click on the options to see examples.

    theme.featuretheme.features

    Material 4.x

    theme:
      feature:
        tabs: true
    

    Material 5.x

    theme:
      features:
        - tabs
        - instant
    
    theme.logo.icontheme.icon.logo

    Material 4.x

    theme:
      logo:
        icon: cloud
    

    Material 5.x

    theme:
      icon:
        logo: material/cloud
    
    extra.repo_icontheme.icon.repo

    Material 4.x

    extra:
      repo_icon: gitlab
    

    Material 5.x

    theme:
      icon:
        repo: fontawesome/brands/gitlab
    
    extra.searchplugins.search

    Material 4.x

    extra:
      search:
        language: en, de, ru
        tokenizer: [\s\-\.]+
    

    Material 5.x

    plugins:
      - search:
          separator: '[\s\-\.]+'
          lang:
            - en
            - de
            - ru
    
    extra.social.*.typeextra.social.*.icon

    Material 4.x

    extra:
      social:
        - type: github
          link: https://github.com/squidfunk
        - type: twitter
          link: https://twitter.com/squidfunk
        - type: linkedin
          link: https://www.linkedin.com/in/squidfunk
    

    Material 5.x

    extra:
      social:
        - icon: fontawesome/brands/github-alt
          link: https://github.com/squidfunk
        - icon: fontawesome/brands/twitter
          link: https://twitter.com/squidfunk
        - icon: fontawesome/brands/linkedin
          link: https://www.linkedin.com/in/squidfunk/
    

    Changes to *.html files

    The templates have undergone a set of necessary changes to make them future-proof. If you've used theme extension to override a template block or HTML file, make sure that the structure of the HTML matches the new structure.

    1. If you've overridden a block, check base.html for potential changes
    2. If you've overridden a template, check the respective *.html file for potential changes
    base.html
    diff --git a/material/base.html b/material/base.html
    index f26b7283..34340f8c 100644
    --- a/material/base.html
    +++ b/material/base.html
    @@ -2,7 +2,6 @@
       This file was automatically generated - do not edit
     -#}
     {% import "partials/language.html" as lang with context %}
    -{% set feature = config.theme.feature %}
     {% set palette = config.theme.palette %}
     {% set font = config.theme.font %}
     <!doctype html>
    @@ -30,21 +29,8 @@
           {% elif config.site_author %}
             <meta name="author" content="{{ config.site_author }}">
           {% endif %}
    -      {% for key in [
    -        "clipboard.copy",
    -        "clipboard.copied",
    -        "search.language",
    -        "search.pipeline.stopwords",
    -        "search.pipeline.trimmer",
    -        "search.result.none",
    -        "search.result.one",
    -        "search.result.other",
    -        "search.tokenizer"
    -      ] %}
    -        <meta name="lang:{{ key }}" content="{{ lang.t(key) }}">
    -      {% endfor %}
           <link rel="shortcut icon" href="{{ config.theme.favicon | url }}">
           <meta name="generator" content="mkdocs-{{ mkdocs_version }}, mkdocs-material-5.0.0b2-1">
         {% endblock %}
         {% block htmltitle %}
           {% if page and page.meta and page.meta.title %}
    @@ -56,9 +42,9 @@
           {% endif %}
         {% endblock %}
         {% block styles %}
    -      <link rel="stylesheet" href="{{ 'assets/stylesheets/application.adb8469c.css' | url }}">
    +      <link rel="stylesheet" href="{{ 'assets/stylesheets/main.14bb5ffa.min.css' | url }}">
           {% if palette.primary or palette.accent %}
    -        <link rel="stylesheet" href="{{ 'assets/stylesheets/application-palette.a8b3c06d.css' | url }}">
    +        <link rel="stylesheet" href="{{ 'assets/stylesheets/palette.f5f04e6f.min.css' | url }}">
           {% endif %}
           {% if palette.primary %}
             {% import "partials/palette.html" as map %}
    @@ -68,25 +54,22 @@
             <meta name="theme-color" content="{{ primary }}">
           {% endif %}
         {% endblock %}
         {% block libs %}
    -      <script src="{{ 'assets/javascripts/modernizr.86422ebf.js' | url }}"></script>
         {% endblock %}
         {% block fonts %}
           {% if font != false %}
             <link href="https://fonts.gstatic.com" rel="preconnect" crossorigin>
             <link rel="stylesheet" href="https://fonts.googleapis.com/css?family={{
                 font.text | replace(' ', '+') + ':300,400,400i,700%7C' +
                 font.code | replace(' ', '+')
               }}&display=fallback">
             <style>body,input{font-family:"{{ font.text }}","Helvetica Neue",Helvetica,Arial,sans-serif}code,kbd,pre{font-family:"{{ font.code }}","Courier New",Courier,monospace}</style>
           {% endif %}
         {% endblock %}
    -    <link rel="stylesheet" href="{{ 'assets/fonts/material-icons.css' | url }}">
         {% if config.extra.manifest %}
           <link rel="manifest" href="{{ config.extra.manifest | url }}" crossorigin="use-credentials">
         {% endif %}
         {% for path in config["extra_css"] %}
           <link rel="stylesheet" href="{{ path | url }}">
         {% endfor %}
         {% block analytics %}
           {% if config.google_analytics %}
    @@ -95,47 +78,46 @@
         {% endblock %}
         {% block extrahead %}{% endblock %}
       </head>
    +  {% set direction = config.theme.direction | default(lang.t('direction')) %}
       {% if palette.primary or palette.accent %}
         {% set primary = palette.primary | replace(" ", "-") | lower %}
         {% set accent  = palette.accent  | replace(" ", "-") | lower %}
    -    <body dir="{{ lang.t('direction') }}" data-md-color-primary="{{ primary }}" data-md-color-accent="{{ accent }}">
    +    <body dir="{{ direction }}" data-md-color-primary="{{ primary }}" data-md-color-accent="{{ accent }}">
       {% else %}
    -    <body dir="{{ lang.t('direction') }}">
    +    <body dir="{{ direction }}">
       {% endif %}
    -    <svg class="md-svg">
    -      <defs>
    -        {% set platform = config.extra.repo_icon or config.repo_url %}
    -        {% if "github" in platform %}
    -          {% include "assets/images/icons/github.f0b8504a.svg" %}
    -        {% elif "gitlab" in platform %}
    -          {% include "assets/images/icons/gitlab.6dd19c00.svg" %}
    -        {% elif "bitbucket" in platform %}
    -          {% include "assets/images/icons/bitbucket.1b09e088.svg" %}
    -        {% endif %}
    -      </defs>
    -    </svg>
         <input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
         <input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
    -    <label class="md-overlay" data-md-component="overlay" for="__drawer"></label>
    +    <label class="md-overlay" for="__drawer"></label>
         {% if page.toc | first is defined %}
    -      <a href="{{ (page.toc | first).url }}" tabindex="0" class="md-skip">
    +      {% set skip = page.toc | first %}
    +      <a href="{{ skip.url | url }}" class="md-skip" data-md-component="skip">
             {{ lang.t('skip.link.title') }}
           </a>
         {% endif %}
    +    {% if self.announce() %}
    +      <aside class="md-announce" data-md-component="announce">
    +        <div class="md-announce__inner md-grid md-typeset">
    +          {% block announce %}{% endblock %}
    +        </div>
    +      </aside>
    +    {% endif %}
         {% block header %}
           {% include "partials/header.html" %}
         {% endblock %}
    -    <div class="md-container">
    +    <div class="md-container" data-md-component="container">
           {% block hero %}
             {% if page and page.meta and page.meta.hero %}
               {% include "partials/hero.html" with context %}
             {% endif %}
           {% endblock %}
    -      {% if feature.tabs %}
    -        {% include "partials/tabs.html" %}
    -      {% endif %}
    +      {% block tabs %}
    +        {% if "tabs" in config.theme.features %}
    +          {% include "partials/tabs.html" %}
    +        {% endif %}
    +      {% endblock %}
    -      <main class="md-main" role="main">
    -        <div class="md-main__inner md-grid" data-md-component="container">
    +      <main class="md-main" data-md-component="main">
    +        <div class="md-main__inner md-grid">
               {% block site_nav %}
                 {% if nav %}
                   <div class="md-sidebar md-sidebar--primary" data-md-component="navigation">
    @@ -160,41 +142,25 @@
                 <article class="md-content__inner md-typeset">
                   {% block content %}
                     {% if page.edit_url %}
    -                  <a href="{{ page.edit_url }}" title="{{ lang.t('edit.link.title') }}" class="md-icon md-content__icon">&#xE3C9;</a>
    +                  <a href="{{ page.edit_url }}" title="{{ lang.t('edit.link.title') }}" class="md-content__button md-icon">
    +                    {% include ".icons/material/pencil.svg" %}
    +                  </a>
                     {% endif %}
    +                {% block source %}
    +                  {% if page and page.meta and page.meta.source %}
    +                    {% include "partials/source-link.html" %}
    +                  {% endif %}
    +                {% endblock %}
                     {% if not "\x3ch1" in page.content %}
                       <h1>{{ page.title | default(config.site_name, true)}}</h1>
                     {% endif %}
                     {{ page.content }}
    -                {% block source %}
    -                  {% if page and page.meta and page.meta.source %}
    -                    <h2 id="__source">{{ lang.t("meta.source") }}</h2>
    -                    {% set repo = config.repo_url %}
    -                    {% if repo | last == "/" %}
    -                      {% set repo = repo[:-1] %}
    -                    {% endif %}
    -                    {% set path = page.meta.path | default([""]) %}
    -                    {% set file = page.meta.source %}
    -                    <a href="{{ [repo, path, file] | join('/') }}" title="{{ file }}" class="md-source-file">
    -                      {{ file }}
    -                    </a>
    -                  {% endif %}
    -                {% endblock %}
    +                {% if page and page.meta %}
    +                  {% if page.meta.git_revision_date_localized or
    +                        page.meta.revision_date
    +                  %}
    +                    {% include "partials/source-date.html" %}
    +                  {% endif %}
    +                {% endblock %}
    -                {% if page and page.meta and (
    -                      page.meta.git_revision_date_localized or
    -                      page.meta.revision_date
    -                ) %}
    -                  {% set label = lang.t("source.revision.date") %}
    -                  <hr>
    -                  <div class="md-source-date">
    -                    <small>
    -                      {% if page.meta.git_revision_date_localized %}
    -                        {{ label }}: {{ page.meta.git_revision_date_localized }}
    -                      {% elif page.meta.revision_date %}
    -                        {{ label }}: {{ page.meta.revision_date }}
    -                      {% endif %}
    -                    </small>
    -                  </div>
    -                {% endif %}
    -              {% endblock %}
                   {% block disqus %}
    @@ -208,29 +174,40 @@
             {% include "partials/footer.html" %}
           {% endblock %}
         </div>
    +    {% block config %}
    +      <script>var __config={}</script>
    +    {% endblock %}
         {% block scripts %}
    -      <script src="{{ 'assets/javascripts/application.df00da5d.js' | url }}"></script>
    -      {% if lang.t("search.language") != "en" %}
    -        {% set languages = lang.t("search.language").split(",") %}
    -        {% if languages | length and languages[0] != "" %}
    -          {% set path = "assets/javascripts/lunr/" %}
    -          <script src="{{ (path ~ 'lunr.stemmer.support.js') | url }}"></script>
    -          {% for language in languages | map("trim") %}
    -            {% if language != "en" %}
    -              {% if language == "ja" %}
    -                <script src="{{ (path ~ 'tinyseg.js') | url }}"></script>
    -              {% endif %}
    -              {% if language in ("ar", "da", "de", "es", "fi", "fr", "hu", "it", "ja", "nl", "no", "pt", "ro", "ru", "sv", "th", "tr", "vi") %}
    -                <script src="{{ (path ~ 'lunr.' ~ language ~ '.js') | url }}"></script>
    -              {% endif %}
    -            {% endif %}
    -          {% endfor %}
    -          {% if languages | length > 1 %}
    -            <script src="{{ (path ~ 'lunr.multi.js') | url }}"></script>
    -          {% endif %}
    -        {% endif %}
    -      {% endif %}
    -      <script>app.initialize({version:"{{ mkdocs_version }}",url:{base:"{{ base_url }}"}})</script>
    +      <script src="{{ 'assets/javascripts/vendor.31a2e7b9.min.js' | url }}"></script>
    +      <script src="{{ 'assets/javascripts/bundle.5b33ad8d.min.js' | url }}"></script>
    +      {%- set translations = {} -%}
    +      {%- for key in [
    +        "clipboard.copy",
    +        "clipboard.copied",
    +        "search.config.lang",
    +        "search.config.pipeline",
    +        "search.config.separator",
    +        "search.result.placeholder",
    +        "search.result.none",
    +        "search.result.one",
    +        "search.result.other"
    +      ] -%}
    +        {%- set _ = translations.update({ key: lang.t(key) }) -%}
    +      {%- endfor -%}
    +      <script id="__lang" type="application/json">
    +        {{ translations | tojson }}
    +      </script>
    +      <script>
    +        __material = initialize(Object.assign({
    +          url: {
    +            base: "{{ base_url }}",
    +            worker: {
    +              search: "{{ 'assets/javascripts/worker/search.edc88caf.min.js' | url }}"
    +            }
    +          },
    +          features: {{ config.theme.features | tojson }}
    +        }, __config))
    +      </script>
           {% for path in config["extra_javascript"] %}
             <script src="{{ path | url }}"></script>
           {% endfor %}
    
    partials/footer.html
    diff --git a/material/partials/footer.html b/material/partials/footer.html
    index c2f5a1c0..ca248f62 100644
    --- a/material/partials/footer.html
    +++ b/material/partials/footer.html
    @@ -7,32 +7,32 @@
         <div class="md-footer-nav">
           <nav class="md-footer-nav__inner md-grid">
             {% if page.previous_page %}
    -          <a href="{{ page.previous_page.url | url }}" title="{{ page.previous_page.title | striptags }}" class="md-flex md-footer-nav__link md-footer-nav__link--prev" rel="prev">
    -            <div class="md-flex__cell md-flex__cell--shrink">
    -              <i class="md-icon md-icon--arrow-back md-footer-nav__button"></i>
    +          <a href="{{ page.previous_page.url | url }}" title="{{ page.previous_page.title | striptags }}" class="md-footer-nav__link md-footer-nav__link--prev" rel="prev">
    +            <div class="md-footer-nav__button md-icon">
    +              {% include ".icons/material/arrow-left.svg" %}
                 </div>
    -            <div class="md-flex__cell md-flex__cell--stretch md-footer-nav__title">
    -              <span class="md-flex__ellipsis">
    +            <div class="md-footer-nav__title">
    +              <div class="md-ellipsis">
                     <span class="md-footer-nav__direction">
                       {{ lang.t("footer.previous") }}
                     </span>
                     {{ page.previous_page.title }}
    -              </span>
    +              </div>
                 </div>
               </a>
             {% endif %}
             {% if page.next_page %}
    -          <a href="{{ page.next_page.url | url }}" title="{{ page.next_page.title | striptags }}" class="md-flex md-footer-nav__link md-footer-nav__link--next" rel="next">
    -            <div class="md-flex__cell md-flex__cell--stretch md-footer-nav__title">
    -              <span class="md-flex__ellipsis">
    +          <a href="{{ page.next_page.url | url }}" title="{{ page.next_page.title | striptags }}" class="md-footer-nav__link md-footer-nav__link--next" rel="next">
    +            <div class="md-footer-nav__title">
    +              <div class="md-ellipsis">
                     <span class="md-footer-nav__direction">
                       {{ lang.t("footer.next") }}
                     </span>
                     {{ page.next_page.title }}
    -              </span>
    +              </div>
                 </div>
    -            <div class="md-flex__cell md-flex__cell--shrink">
    -              <i class="md-icon md-icon--arrow-forward md-footer-nav__button"></i>
    +            <div class="md-footer-nav__button md-icon">
    +              {% include ".icons/material/arrow-right.svg" %}
                 </div>
               </a>
             {% endif %}
    
    partials/header.html
    diff --git a/material/partials/header.html b/material/partials/header.html
    index cfaf1a3b..90438e8c 100644
    --- a/material/partials/header.html
    +++ b/material/partials/header.html
    @@ -3,50 +3,44 @@
     -#}
     <header class="md-header" data-md-component="header">
       <nav class="md-header-nav md-grid">
    -    <div class="md-flex">
    -      <div class="md-flex__cell md-flex__cell--shrink">
    -        <a href="{{ config.site_url | default(nav.homepage.url, true) | url }}" title="{{ config.site_name }}" aria-label="{{ config.site_name }}" class="md-header-nav__button md-logo">
    -          {% if config.theme.logo.icon %}
    -            <i class="md-icon">{{ config.theme.logo.icon }}</i>
    -          {% else %}
    -            <img alt="logo" src="{{ config.theme.logo | url }}" width="24" height="24">
    -          {% endif %}
    -        </a>
    -      </div>
    -      <div class="md-flex__cell md-flex__cell--shrink">
    -        <label class="md-icon md-icon--menu md-header-nav__button" for="__drawer"></label>
    -      </div>
    -      <div class="md-flex__cell md-flex__cell--stretch">
    -        <div class="md-flex__ellipsis md-header-nav__title" data-md-component="title">
    -          {% if config.site_name == page.title %}
    +    <a href="{{ config.site_url | default(nav.homepage.url, true) | url }}" title="{{ config.site_name }}" aria-label="{{ config.site_name }}" class="md-header-nav__button md-logo">
    +      {% if config.theme.logo %}
    +        <img src="{{ config.theme.logo | url }}" alt="logo">
    +      {% else %}
    +        {% include ".icons/" ~ config.theme.icon.logo ~ ".svg" %}
    +      {% endif %}
    +    </a>
    +    <label class="md-header-nav__button md-icon" for="__drawer">
    +      {% include ".icons/material/menu" ~ ".svg" %}
    +    </label>
    +    <div class="md-header-nav__title" data-md-component="header-title">
    +      <div class="md-header-nav__ellipsis md-ellipsis">
    +        {% if config.site_name == page.title %}
    +          {{ config.site_name }}
    +        {% else %}
    +          <span class="md-header-nav__topic">
                 {{ config.site_name }}
    -          {% else %}
    -            <span class="md-header-nav__topic">
    -              {{ config.site_name }}
    -            </span>
    -            <span class="md-header-nav__topic">
    -              {% if page and page.meta and page.meta.title %}
    -                {{ page.meta.title }}
    -              {% else %}
    -                {{ page.title }}
    -              {% endif %}
    -            </span>
    -          {% endif %}
    -        </div>
    -      </div>
    -      <div class="md-flex__cell md-flex__cell--shrink">
    -        {% if "search" in config["plugins"] %}
    -          <label class="md-icon md-icon--search md-header-nav__button" for="__search"></label>
    -          {% include "partials/search.html" %}
    +          </span>
    +          <span class="md-header-nav__topic">
    +            {% if page and page.meta and page.meta.title %}
    +              {{ page.meta.title }}
    +            {% else %}
    +              {{ page.title }}
    +            {% endif %}
    +          </span>
             {% endif %}
           </div>
    -      {% if config.repo_url %}
    -        <div class="md-flex__cell md-flex__cell--shrink">
    -          <div class="md-header-nav__source">
    -            {% include "partials/source.html" %}
    -          </div>
    -        </div>
    -      {% endif %}
         </div>
    +    {% if "search" in config["plugins"] %}
    +      <label class="md-header-nav__button md-icon" for="__search">
    +        {% include ".icons/material/magnify.svg" %}
    +      </label>
    +      {% include "partials/search.html" %}
    +    {% endif %}
    +    {% if config.repo_url %}
    +      <div class="md-header-nav__source">
    +        {% include "partials/source.html" %}
    +      </div>
    +    {% endif %}
       </nav>
     </header>
    
    partials/hero.html
    diff --git a/material/partials/hero.html b/material/partials/hero.html
    index 3d6a2cc8..2c244e18 100644
    --- a/material/partials/hero.html
    +++ b/material/partials/hero.html
    @@ -1,9 +1,8 @@
     {#-
       This file was automatically generated - do not edit
     -#}
    -{% set feature = config.theme.feature %}
     {% set class = "md-hero" %}
    -{% if not feature.tabs %}
    +{% if "tabs" not in config.theme.features %}
       {% set class = "md-hero md-hero--expand" %}
     {% endif %}
     <div class="{{ class }}" data-md-component="hero">
    
    partials/language.html
    diff --git a/material/partials/language.html b/material/partials/language.html
    index d0314ffc..46188a6b 100644
    --- a/material/partials/language.html
    +++ b/material/partials/language.html
    @@ -3,12 +3,4 @@
     -#}
     {% import "partials/language/" + config.theme.language + ".html" as lang %}
     {% import "partials/language/en.html" as fallback %}
    -{% macro t(key) %}{{ {
    -  "direction": config.theme.direction,
    -  "search.language": (
    -    config.extra.search | default({})
    -  ).language,
    -  "search.tokenizer": (
    -    config.extra.search | default({})
    -  ).tokenizer | default("", true),
    -}[key] or lang.t(key) or fallback.t(key) }}{% endmacro %}
    +{% macro t(key) %}{{ lang.t(key) | default(fallback.t(key)) }}{% endmacro %}
    
    partials/nav-item.html
    diff --git a/material/partials/nav-item.html b/material/partials/nav-item.html
    index 54c06034..15e626ab 100644
    --- a/material/partials/nav-item.html
    +++ b/material/partials/nav-item.html
    @@ -8,15 +8,21 @@
     {% if nav_item.children %}
       <li class="{{ class }} md-nav__item--nested">
         {% if nav_item.active %}
           <input class="md-nav__toggle md-toggle" data-md-toggle="{{ path }}" type="checkbox" id="{{ path }}" checked>
         {% else %}
           <input class="md-nav__toggle md-toggle" data-md-toggle="{{ path }}" type="checkbox" id="{{ path }}">
         {% endif %}
         <label class="md-nav__link" for="{{ path }}">
           {{ nav_item.title }}
    +      <span class="md-nav__icon md-icon">
    +        {% include ".icons/material/chevron-right.svg" %}
    +      </span>
         </label>
    -    <nav class="md-nav" data-md-component="collapsible" data-md-level="{{ level }}">
    +    <nav class="md-nav" data-md-level="{{ level }}">
           <label class="md-nav__title" for="{{ path }}">
    +        <span class="md-nav__icon md-icon">
    +          {% include ".icons/material/arrow-left.svg" %}
    +        </span>
             {{ nav_item.title }}
           </label>
           <ul class="md-nav__list" data-md-scrollfix>
    @@ -32,13 +38,16 @@
     {% elif nav_item == page %}
       <li class="{{ class }}">
         {% set toc_ = page.toc %}
         <input class="md-nav__toggle md-toggle" data-md-toggle="toc" type="checkbox" id="__toc">
         {% if toc_ | first is defined and "\x3ch1 id=" in page.content %}
           {% set toc_ = (toc_ | first).children %}
         {% endif %}
         {% if toc_ | first is defined %}
           <label class="md-nav__link md-nav__link--active" for="__toc">
             {{ nav_item.title }}
    +        <span class="md-nav__icon md-icon">
    +          {% include ".icons/material/table-of-contents.svg" %}
    +        </span>
           </label>
         {% endif %}
         <a href="{{ nav_item.url | url }}" title="{{ nav_item.title | striptags }}" class="md-nav__link md-nav__link--active">
    
    partials/nav.html
    diff --git a/material/partials/nav.html b/material/partials/nav.html
    index b72383d4..0735f58e 100644
    --- a/material/partials/nav.html
    +++ b/material/partials/nav.html
    @@ -2,12 +2,12 @@
       This file was automatically generated - do not edit
     -#}
     <nav class="md-nav md-nav--primary" data-md-level="0">
    -  <label class="md-nav__title md-nav__title--site" for="__drawer">
    -    <a href="{{ config.site_url | default(nav.homepage.url, true) | url }}" title="{{ config.site_name }}" class="md-nav__button md-logo">
    -      {% if config.theme.logo.icon %}
    -        <i class="md-icon">{{ config.theme.logo.icon }}</i>
    +  <label class="md-nav__title" for="__drawer">
    +    <a href="{{ config.site_url | default(nav.homepage.url, true) | url }}" title="{{ config.site_name }}" aria-label="{{ config.site_name }}" class="md-nav__button md-logo">
    +      {% if config.theme.logo %}
    +        <img src="{{ config.theme.logo | url }}" alt="logo">
           {% else %}
    -        <img alt="logo" src="{{ config.theme.logo | url }}" width="48" height="48">
    +        {% include ".icons/" ~ config.theme.icon.logo ~ ".svg" %}
           {% endif %}
         </a>
         {{ config.site_name }}
    
    partials/search.html
    diff --git a/material/partials/search.html b/material/partials/search.html
    index 4863b708..4510355b 100644
    --- a/material/partials/search.html
    +++ b/material/partials/search.html
    @@ -6,15 +6,18 @@
       <label class="md-search__overlay" for="__search"></label>
       <div class="md-search__inner" role="search">
         <form class="md-search__form" name="search">
    -      <input type="text" class="md-search__input" aria-label="search" name="query" placeholder="{{ lang.t('search.placeholder') }}" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="query" data-md-state="active">
    +      <input type="text" class="md-search__input" name="query" aria-label="search" placeholder="{{ lang.t('search.placeholder') }}" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="search-query" data-md-state="active" required>
           <label class="md-search__icon md-icon" for="__search">
    +        {% include ".icons/material/magnify.svg" %}
    +        {% include ".icons/material/arrow-left.svg" %}
           </label>
    -      <button type="reset" class="md-icon md-search__icon" data-md-component="reset" tabindex="-1">
    -        &#xE5CD;
    +      <button type="reset" class="md-search__icon md-icon" data-md-component="search-reset" tabindex="-1">
    +        {% include ".icons/material/close.svg" %}
           </button>
         </form>
         <div class="md-search__output">
           <div class="md-search__scrollwrap" data-md-scrollfix>
    -        <div class="md-search-result" data-md-component="result">
    +        <div class="md-search-result" data-md-component="search-result">
               <div class="md-search-result__meta">
                 {{ lang.t("search.result.placeholder") }}
               </div>
    
    partials/social.html
    diff --git a/material/partials/social.html b/material/partials/social.html
    index 391385e5..8b4ebdfe 100644
    --- a/material/partials/social.html
    +++ b/material/partials/social.html
    @@ -3,9 +3,10 @@
     -#}
     {% if config.extra.social %}
       <div class="md-footer-social">
    -    <link rel="stylesheet" href="{{ 'assets/fonts/font-awesome.css' | url }}">
         {% for social in config.extra.social %}
    -      <a href="{{ social.link }}" target="_blank" rel="noopener" title="{{ social.type }}" class="md-footer-social__link fa fa-{{ social.type }}"></a>
    +      <a href="{{ social.link }}" target="_blank" rel="noopener" class="md-footer-social__link">
    +        {% include ".icons/" ~ social.icon ~ ".svg" %}
    +      </a>
         {% endfor %}
       </div>
     {% endif %}
    
    partials/source-date.html
    diff --git a/material/partials/source-date.html b/material/partials/source-date.html
    new file mode 100644
    index 00000000..9c72b8bc
    --- /dev/null
    +++ b/material/partials/source-date.html
    @@ -0,0 +1,15 @@
    +{#-
    +  This file was automatically generated - do not edit
    +-#}
    +{% import "partials/language.html" as lang with context %}
    +{% set label = lang.t("source.revision.date") %}
    +<hr>
    +<div class="md-source-date">
    +  <small>
    +    {% if page.meta.git_revision_date_localized %}
    +      {{ label }}: {{ page.meta.git_revision_date_localized }}
    +    {% elif page.meta.revision_date %}
    +      {{ label }}: {{ page.meta.revision_date }}
    +    {% endif %}
    +  </small>
    +</div>
    
    partials/source-link.html
    diff --git a/material/partials/source-link.html b/material/partials/source-link.html
    new file mode 100644
    index 00000000..86418fa1
    --- /dev/null
    +++ b/material/partials/source-link.html
    @@ -0,0 +1,17 @@
    +{#-
    +  This file was automatically generated - do not edit
    +-#}
    +{% import "partials/language.html" as lang with context %}
    +{% set repo = config.repo_url %}
    +{% if repo | last == "/" %}
    +  {% set repo = repo[:-1] %}
    +{% endif %}
    +{% set path = page.meta.path | default([""]) %}
    +{% set file = page.meta.source %}
    +{% set repo_icon = config.extra.repo_icon | default(
    +  "fontawesome/brands/git-alt"
    +) %}
    +<a href="{{ [repo, path, page.meta.source] | join('/') }}" title="{{ file }}" class="md-content__button md-icon">
    +  {{ lang.t("meta.source") }}
    +  {% include ".icons/" ~ repo_icon ~ ".svg" %}
    +</a>
    
    partials/source.html
    diff --git a/material/partials/source.html b/material/partials/source.html
    index 742d42de..a65295a4 100644
    --- a/material/partials/source.html
    +++ b/material/partials/source.html
    @@ -2,24 +2,10 @@
       This file was automatically generated - do not edit
     -#}
     {% import "partials/language.html" as lang with context %}
    -{% set platform = config.extra.repo_icon or config.repo_url %}
    -{% if "github" in platform %}
    -  {% set repo_type = "github" %}
    -{% elif "gitlab" in platform %}
    -  {% set repo_type = "gitlab" %}
    -{% elif "bitbucket" in platform %}
    -  {% set repo_type = "bitbucket" %}
    -{% else %}
    -  {% set repo_type = "" %}
    -{% endif %}
    -<a href="{{ config.repo_url }}" title="{{ lang.t('source.link.title') }}" class="md-source" data-md-source="{{ repo_type }}">
    -  {% if repo_type %}
    -    <div class="md-source__icon">
    -      <svg viewBox="0 0 24 24" width="24" height="24">
    -        <use xlink:href="#__{{ repo_type }}" width="24" height="24"></use>
    -      </svg>
    -    </div>
    -  {% endif %}
    +<a href="{{ config.repo_url }}" title="{{ lang.t('source.link.title') }}" class="md-source">
    +  <div class="md-source__icon md-icon">
    +    {% include ".icons/" ~ config.theme.icon.repo ~ ".svg" %}
    +  </div>
       <div class="md-source__repository">
         {{ config.repo_name }}
       </div>
    
    partials/tabs-item.html
    diff --git a/material/partials/tabs-item.html b/material/partials/tabs-item.html
    index 1f3179d3..64ced43b 100644
    --- a/material/partials/tabs-item.html
    +++ b/material/partials/tabs-item.html
    @@ -1,7 +1,7 @@
     {#-
       This file was automatically generated - do not edit
     -#}
    -{% if nav_item.is_homepage %}
    +{% if nav_item.is_homepage or nav_item.url == "index.html" %}
       <li class="md-tabs__item">
         {% if not page.ancestors | length and nav | selectattr("url", page.url) %}
           <a href="{{ nav_item.url | url }}" class="md-tabs__link md-tabs__link--active">
    
    partials/toc.html
    diff --git a/material/partials/toc.html b/material/partials/toc.html
    index 14a5e070..db4cfbea 100644
    --- a/material/partials/toc.html
    +++ b/material/partials/toc.html
    @@ -3,34 +3,21 @@
     -#}
     {% import "partials/language.html" as lang with context %}
     <nav class="md-nav md-nav--secondary">
       {% set toc = page.toc %}
       {% if toc | first is defined and "\x3ch1 id=" in page.content %}
         {% set toc = (toc | first).children %}
       {% endif %}
       {% if toc | first is defined %}
         <label class="md-nav__title" for="__toc">
    +      <span class="md-nav__icon md-icon">
    +        {% include ".icons/material/arrow-left.svg" %}
    +      </span>
           {{ lang.t("toc.title") }}
         </label>
         <ul class="md-nav__list" data-md-scrollfix>
           {% for toc_item in toc %}
             {% include "partials/toc-item.html" %}
           {% endfor %}
    -      {% if page.meta.source and page.meta.source | length > 0 %}
    -        <li class="md-nav__item">
    -          <a href="#__source" class="md-nav__link md-nav__link--active">
    -            {{ lang.t("meta.source") }}
    -          </a>
    -        </li>
    -      {% endif %}
    -      {% set disqus = config.extra.disqus %}
    -      {% if page and page.meta and page.meta.disqus is string %}
    -        {% set disqus = page.meta.disqus %}
    -      {% endif %}
    -      {% if not page.is_homepage and disqus %}
    -        <li class="md-nav__item">
    -          <a href="#__comments" class="md-nav__link md-nav__link--active">
    -            {{ lang.t("meta.comments") }}
    -          </a>
    -        </li>
    -      {% endif %}
         </ul>
       {% endif %}
     </nav>
    

    Notes

    Instant loading

    The basic idea is: why should we reconstruct the whole page again and again when only the content and navigation changes? When instant loading is enabled, all internal links are intercepted and dispatched via XHR. The resulting document is parsed, injected and all event handlers are automatically rebound. The search index will remain intact in-between loads.

    With instant loading enabled, Material effectively behaves like a Single Page Application.

    This feature shows the true beauty of the new architecture - everything is observable and automatically updates when new values become available. The following gifs were recorded on Fast 3G to show the speed advantage of instant loading:

    Without instant loading

    No Instant Loading

    With instant loading

    Instant Loading

    Social links

    FontAwesome was updated to the latest version and is now provided via inline SVGs which reduces the overall footprint. To reference an icon, reference its path from the top-level .icons directory which is distributed with the theme without the .svg at the end. Besides FontAwesome, the Material icons and GitHub's octicons are also bundled with the theme.

    Note that mkdocs build will now terminate with an error if an invalid icon is referenced.

    Known bugs

    • [x] Instant loading sometimes doubles the URL (race condition) 80f1d3e3
    • [x] direction="None" when no direction is set 584eac86

    Feedback is appreciated!

    help wanted 
    opened by squidfunk 60
  • Code-tabs extension support request

    Code-tabs extension support request

    Hello @squidfunk, first off, thanks for your great job with material theme! 😊

    I'm working on a new version of the markdown-fenced-code-tabs extension and i will be happy if it could be supported by the mkdocs-material.

    The current version generates tabs exclusively as Bootstrap3 HTML template 😞.

    But the new version i'm working on and which is already ready offerts the option to choose the rendering template. You can choose bootstrap3, bootstrap4 or default.

    There is any chance that you support the default-template ? 😊

    Here is the branch link for the new version.

    Let me know if you need more details or if you have any suggestions.

    enhancement fix available input needed 
    opened by yacir 55
  • Feature suggestion: Blog

    Feature suggestion: Blog

    I've been thinking on and off about blog support and think it is ready to be tackled. I want to provide native blog support for Material for MkDocs, which can be used just as easily as the overall project. Before I start implementing, I want to collect some ideas and requirements, so that we can gravitate towards a solution that ticks as many boxes as possible.

    Collected ideas (checked means implemented)

    • [x] Auto-generate blog index page and article pages @squidfunk
    • [x] Auto-generate archive index pages with chronologically sorted posts @hellt
    • [x] Auto-generate final URL from date (format can be changed) + title @squidfunk
    • [x] Provide a pagination of the index page @squidfunk
    • [x] Integrate with the built-in tags plugin @squidfunk, @hellt
    • [x] Allow to provide author information that is automatically rendered @squidfunk, @hellt, @ben519
    • [x] Allow to provide static pages alongside articles @squidfunk
    • [x] Allow authors to easily override/extend templates @squidfunk
    • [x] Allow for completely flexible structuring of blog posts @Andre601, @timvink
    • [x] Allow to disable prev/next (use front matter + built-in meta plugin) @Andre601
    • [x] Allow for lightbox/gallery integration (use lightbox integration) @Andre601
    • [x] Allow to broadcast notifications (use RSS plugin) @mfridman, @sheldonhull, @Andre601
    • [x] Allow for multiple authors per post @shokinn
    • [x] Allow to mark posts as drafts @dcode
    • [x] Allow to automatically mark posts as drafts if they have a future date @dcode
    • [x] Allow for automatically estimated reading time @hellt
    • [x] Allow for standalone blog @sheldonhull
    • [x] Allow for defining custom slug schemes @sheldonhull
    • [x] Allow for overriding slugs per post @sheldonhull
    • [x] Allow blog posts to be assigned to categories @Andre601
    • [x] Allow default settings per category (use built-in meta plugin) @Andre601
    • [x] Auto-generated category index pages @Andre601
    • [x] Allow to disable table of content in blog post (use front matter + built-in meta plugin) @birdybro
    • [x] Allow flexible naming for source files @SilentGlasses
    • [x] Allow to easily migrate from other blog solutions @Realvincentyuan

    Possibly implementable

    • [ ] Add share-out links to share a post on social media @mfridman, @eyllanesc, @ben519
    • [ ] Allow for combining blog posts into series @eyllanesc
    • [ ] Allow to generate a post overview per author @shokinn
    • [ ] Expose latest posts via template variables @timvink, @kcgthb

    Possibly not going to be implemented

    • [ ] Allow to upvote blog posts – unclear how this should be persisted @LuciferUchiha
    • [ ] Allow for sourcing blog posts from GitHub issues @sheldonhull
    • [ ] Allow for configurable prev/next buttons in the footer @ben519
    • [ ] Allow to segregate blog search results from documentation @birdybro
    • [ ] Faster builds (this is an upstream MkDocs issue) @Realvincentyuan

    Feel free to leave further input in the comments

    • What navigation and directory structure would you expect from a blog?
    • What pages besides the index page do you need? Archive? Tags?
    • How would you write a new blog article, i.e., what's the expected DX?
    • ... anything else that's on your mind
    enhancement fix available 
    opened by squidfunk 48
  • Material 5.0.0 Beta 1

    Material 5.0.0 Beta 1

    This thread is meant for feedback on the first beta release of Material 5.0. Please post any issues or errors encountered during setup and/or migration.

    The first beta focuses on the rewrite of the underlying JavaScript code to a new, more modern architecture based on TypeScript and RxJS. However, it also provides some new features.

    The probably biggest feature is the new search functionality which was completely rewritten and is now running inside a web worker. Furthermore, it supports prebuilt indexes (albeit this is not recommended). Previously, the search index was built when the search was focussed for the first time. Sometimes this led to lags and the UI freezing, as the search index needed to be constructed. The construction is now done upon page load inside a web worker.

    Additionally, most of lunr's query syntax is now supported, e.g.:

    color -primary +accent
    

    Fixed issues

    • [x] Add 'selected' as toc item state (#1102)
    • [x] Update Font Awesome to LATEST (#756)
    • [x] Fix rendering issues in table of contents (#1292)
    • [x] Add announcement bar (#1190)
    • [x] Add missing background-color definition on root (#1418)
    • [x] Fix error on clipboard in combination with superfences (#1440)

    Installation

    Install the beta via pip:

    pip install mkdocs-material>=5.0.0b1
    

    Migration

    Material 5.0 is mostly downward compatible but includes some breaking changes. Following is a list of changes that need to be made to your mkdocs.yml. Note that you only need to adjust the values if you defined them.

    Search

    Search is now configured as part of the search plugin configuration.

    Material 4.x:

    extra:
      search:
        language: 'en, de, ru'
        tokenizer: '[\s\-\.]+'
    

    Material 5.x:

    plugins:
      - search:
          separator: '[\s\-\.]+'
          lang:
            - en
            - de
            - ru
    

    Social links

    Font Awesome was updated to the latest version and is now provided via inline SVGs which reduces the overall footprint. To reference an icon, reference its path from the top-level .fontawesome directory which is distributed with the theme without the .svg at the end.

    Material 4.x:

    extra:
      social:
        - type: 'github'
          link: 'https://github.com/squidfunk'
        - type: 'twitter'
          link: 'https://twitter.com/squidfunk'
        - type: 'linkedin'
          link: 'https://www.linkedin.com/in/squidfunk'
    

    Material 5.x:

    extra:
      social:
        - icon: brands/github-alt
          link: https://github.com/squidfunk
        - icon: brands/twitter
          link: https://twitter.com/squidfunk
        - icon: brands/linkedin
          link: https://www.linkedin.com/in/squidfunk/
    

    Note that mkdocs build will now terminate with an error if an invalid icon is referenced.

    Templates

    Note that some of the templates changed. If you extended the theme by overriding blocks or partials, you might have to adjust the HTML of your overrides. We're working on a list of changes, but for now you can use the diff functionality of GitHub.

    opened by squidfunk 47
  • Currently not GDPR compliant - reason external fonts

    Currently not GDPR compliant - reason external fonts

    Description

    As in EU the GDPR starts to be active from May 25th on. It would be good if all external fonts and services are part of the bundle and do not link to the CDN version. Otherwise we have to display a cookie consent and a privacy policy for a "documentation".

    Expected behavior

    Please include the Material Icons and Roboto Font directly (and other external services) into the bundle at least everything which is needed for the default material theme. Currently it is not GDPR compliant how it is right now.

    Actual behavior

    It's loaded from a CDN.

    Steps to reproduce the bug

    In the Base.html (maybe in other files as well) from the material design there are links to the CDN services.

    proposal 
    opened by DsrMedia 46
  • Open discussion and suggestions

    Open discussion and suggestions

    Hi,

    First off, thank you -- I'm super psyched to see a theme for MkDocs outside of the readthedocs standard that I both enjoy and find it to work for the style of the documentation I tend to write.

    • What are your thoughts on having the project logo display either at the top of each page or in the coloured material header when displaying the docs in tablet/mobile view?
    • The admonition UI seems a bit too bland, I'm not sure what I'd like to see change, however, I'll give it some thought and update here if I come up with something more concrete. I did see some really cool extensions of the admonition style used in Microsoft's Office Online docs, however, they're using Sphinx, thought I'd pass this along though. http://wopi.readthedocs.org/en/latest/contributing/style_guide.html. Perhaps use the Material Design icons for alert, etc in the admonition styles as seen here: https://design.google.com/icons/
    • What are your thoughts on adding a "Edit on Github" or "Fork on Github" type option to the mkdocs.yml configurations? I like the Github stars, however, the download button to me seems like it's a bit unclear as to why a user would download this/what they may be downloading exactly. Something like this may be nice with a bit more material design style: https://github.com/tholman/github-corners
    • On http://squidfunk.github.io/mkdocs-material/getting-started/ you're showing a version variable. I couldn't find where this is displayed anywhere on the demo site, did I miss something?

    Once again, I absolutely love this theme and thank you for creating it. I just wanted to provide some thoughts I had when testing it out with one of my mkdocs sites.

    I'm happy to help out in any way that I can. Thanks again!

    screenshot2-10-1607 04

    proposal 
    opened by brianjking 44
  • Material 5.0.0 Beta 2

    Material 5.0.0 Beta 2

    This thread is meant for feedback on the second beta release of Material 5.0. Please post any issues or errors encountered during setup and/or migration.

    The second beta includes several bugfixes and also adds some new features.

    Instant loading

    Theory of operation

    The basic idea is: why should we reconstruct the whole page again and again when only the content and navigation changes? When instant loading is enabled, all internal links are intercepted and dispatched via XHR. The resulting document is parsed, injected and all event handlers are automatically rebound. The search index will remain intact in-between loads.

    With instant loading enabled, Material effectively behaves like a Single Page Application.

    This feature shows the true beauty of the new architecture - everything is observable and automatically updates when new values become available. However, instant loading is experimental. It will definitely be part of the next major version, but will remain in an experimental state until we fleshed out the biggest bugs. It will at all times remain opt-in, thus it has to be enabled explicitly:

    theme:
      feature:
        instant: true
    

    Demo

    The following gifs were recorded on Fast 3G to show the speed advantage of instant loading:

    Without instant loading

    No Instant Loading

    With instant loading

    Instant Loading

    Known bugs

    • [x] When a link from the search is clicked, the browser doesn't jump to the right place
    • [x] Google Analytics is not triggered again
    • [x] Search doesn't work when use_directory_urls is set to false
    • [x] Scroll snap on 2nd+ tab for screen navigation doesn't correctly lock into place

    All fixed in HEAD of refactor/rxjs-typescript

    Changelog

    Bugfixes

    • [x] Fixed multi-language search not being correctly initialized
    • [x] Fixed invalid anchor list offset for hidden anchors
    • [x] Fixed failing anchor jump for anchors inside closed details
    • [x] Lots and lots of other small improvements

    Features

    • [x] Added new experimental theme.feature.instant configuration option
    • [x] Added p / , (previous page) and n / . (next page) hotkeys
    • [x] Added support for variable sized header – sidebars now lock correctly into place
    • [x] Added a generic snackbar implementation, currently only used by copy-to-clipboard
    • [x] Added GitLab support (stars + forks retrieval)

    Installation

    pip install mkdocs-material>=5.0.0b2
    

    Migration

    Material 5.0 is mostly downward compatible but includes some breaking changes. Following is a list of changes that need to be made to your mkdocs.yml. Note that you only need to adjust the values if you defined them.

    Search

    Search is now configured as part of the search plugin configuration.

    Material 4.x:

    extra:
      search:
        language: en, de, ru
        tokenizer: [\s\-\.]+
    

    Material 5.x:

    plugins:
      - search:
          separator: '[\s\-\.]+'
          lang:
            - en
            - de
            - ru
    

    Social links

    Font Awesome was updated to the latest version and is now provided via inline SVGs which reduces the overall footprint. To reference an icon, reference its path from the top-level .fontawesome directory which is distributed with the theme without the .svg at the end.

    Material 4.x:

    extra:
      social:
        - type: github
          link: https://github.com/squidfunk
        - type: twitter
          link: https://twitter.com/squidfunk
        - type: linkedin
          link: https://www.linkedin.com/in/squidfunk
    

    Material 5.x:

    extra:
      social:
        - icon: brands/github-alt
          link: https://github.com/squidfunk
        - icon: brands/twitter
          link: https://twitter.com/squidfunk
        - icon: brands/linkedin
          link: https://www.linkedin.com/in/squidfunk/
    

    Note that mkdocs build will now terminate with an error if an invalid icon is referenced.

    Feedback is appreciated!

    help wanted 
    opened by squidfunk 43
  • Accessible Navigation for Nested nav-items

    Accessible Navigation for Nested nav-items

    Contribution guidelines

    I want to suggest an idea and checked that ...

    • [X] ... to my best knowledge, my idea wouldn't break something for other users
    • [X] ... the documentation does not mention anything about my idea
    • [X] ... there are no open or closed issues that are related to my idea

    Description

    I propose adding tabindex, aria-hidden, and aria-expanded attributes to the labels on nested nav-items. I would also like to add event listeners to those same labels such that when they are in focus the user can click enter to expand them.

    Use Cases

    This would make the nav bar easier to use for visually impaired users. As it stands, they aren't tabbable, and just adding tabindex="0" doesn't make it better because they still need to be clicked on to expand. This is why the event listeners are also necessary.

    Screenshots / Mockups

    Here's a link to my suggested solution: https://github.com/mnazzaro/mkdocs-material

    It still has some problems, though, as described in my comment in discussion 3156: https://github.com/squidfunk/mkdocs-material/discussions/3156#discussioncomment-4501461

    No response

    enhancement 
    opened by mnazzaro 1
  • Typeset plugin changes precedence of nav entry over h1

    Typeset plugin changes precedence of nav entry over h1

    Contribution guidelines

    I've found a bug and checked that ...

    • [X] ... the problem doesn't occur with the mkdocs or readthedocs themes
    • [X] ... the problem persists when all overrides are removed, i.e. custom_dir, extra_javascript and extra_css
    • [X] ... the documentation does not mention anything about my problem
    • [X] ... there are no open or closed issues that are related to my problem

    Description

    When the typeset plugin is enabled, a page's heading 1 takes precedence over the nav entry when determining the navigation title. Normally, this is vice versa.

    This means that with the following configuration, the navigation title will be "My Topic Title" instead of "My Nav Title":

    index.md:

    # My Topic Title
    
    Lorem ipsum
    

    mkdocs.yml:

    nav:
      - My Nav Title: index.md
      - Topic: topic.md
    ...
    plugins:
      - search
      - typeset
    

    This may be desirable if you want to use Markdown formatting in the navigation, but I think there should be an option to override this behavior. For example, you may want nav titles that are shorter than the h1.

    Also, I think it should be documented that if you want to apply Markdown formatting to the navigation, you actually have to do that via the h1, and not via mkdocs.yml.

    Sample project: typeset-sample.zip

    Expected behaviour

    See description.

    Actual behaviour

    See description.

    Steps to reproduce

    See description.

    Package versions

    • Python: 3.11
    • MkDocs: 1.4.2
    • Material: latest Insiders version

    Configuration

    See description.
    

    System information

    • Operating system: macOS
    • Browser: FF
    bug 
    opened by wilhelmer 0
  • Mermaid sequence diagrams: alt fragment titles rendering in odd ways

    Mermaid sequence diagrams: alt fragment titles rendering in odd ways

    Contribution guidelines

    I've found a bug and checked that ...

    • [X] ... the problem doesn't occur with the mkdocs or readthedocs themes
    • [X] ... the problem persists when all overrides are removed, i.e. custom_dir, extra_javascript and extra_css
    • [X] ... the documentation does not mention anything about my problem
    • [X] ... there are no open or closed issues that are related to my problem - there is a related problem but not exactly the same: #4713

    Description

    Mermaid's sequence diagrams support alt fragements: https://mermaid.js.org/syntax/sequenceDiagram.html#alt

    They work great! However in light mode some of the titles are bolded and then when switching to dark mode some of the titles are unreadable.

    Light mode issue: image

    Dark mode issue: image

    Expected behaviour

    The titles should be readable and consistent fonts

    Actual behaviour

    Some titles are bold, and black on black text is not readable

    Steps to reproduce

    Create a sequence diagram like so:

    sequenceDiagram
        Alice->>Bob: Hello Bob, how are you?
        alt is sick
            Bob->>Alice: Not so good :(
        else is well
            Bob->>Alice: Feeling fresh like a daisy
        end
        opt Extra response
            Bob->>Alice: Thanks for asking
        end
    

    Toggle between light and dark mode.

    Package versions

    • Python: Python 3.9.7
    • MkDocs: mkdocs, version 1.4.2
    • Material: Version: 8.5.11

    Configuration

    site_name: Test
    nav:
      - Home: index.md
    theme:
      name: material
      palette:
      - media: "(prefers-color-scheme: light)"
        scheme: default
        toggle:
          icon: material/brightness-7
          name: Switch to dark mode
      - media: "(prefers-color-scheme: dark)"
        scheme: slate
        toggle:
          icon: material/brightness-4
          name: Switch to light mode 
        primary: indigo
        accemt: yellow
    markdown_extensions:
      - pymdownx.superfences:
          custom_fences:
            - name: mermaid
              class: mermaid
              format: !!python/name:pymdownx.superfences.fence_code_format
    

    System information

    • Operating system: Windows
    • Browser: Firefox
    bug good first issue 
    opened by imkacarlson 6
  • Blog post do not have a table of contents with toc.integrate enabled.

    Blog post do not have a table of contents with toc.integrate enabled.

    Contribution guidelines

    I've found a bug and checked that ...

    • [X] ... the problem doesn't occur with the mkdocs or readthedocs themes
    • [X] ... the problem persists when all overrides are removed, i.e. custom_dir, extra_javascript and extra_css
    • [X] ... the documentation does not mention anything about my problem
    • [X] ... there are no open or closed issues that are related to my problem

    Description

    With toc.integrate enabled, blog posts do not have a table of contents.

    Expected behaviour

    Preferably, the table of the contents should appear on the left side of the blog post, above author information and metadata.

    Actual behaviour

    Blog posts lack a TOC, appearing neither left or right.

    Steps to reproduce

    Enable toc.integrate within mkdocs.yml

    Package versions

    • Python: 3.11
    • MkDocs: Insiders commit 78de2df
    • Material: 1.4.2

    Configuration

    features:
       - toc.integrate
    

    System information

    • Operating system: Windows 11
    • Browser: Firefox
    bug 
    opened by tylernguyen 7
  • 🚀 Material for MkDocs 9 – Beta

    🚀 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

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

    Removals

    Fixes

    • [x] Fixed Korean language code (~~kr~~ ko) in 5aebaaa71
    • [x] Fixed detection of composition events in search interface
    • [x] Fixed search plugin not using title set via front matter
    • [x] Fixed search highlighting of tags in 24a3be8
    • [x] Fixed search sharing URL using post transformed string (with wildcards etc.)
    • [x] Fixed inability to query specific fields (e.g. tags:foo or title:bar)
    • [x] Fixed inability to exclude search terms (e.g. -foo or -title:bar)
    • [x] Fixed inability to use fuzzy modifier (e.g. foo~1 or title:bar~2)
    • [x] Fixed inability to boost specific terms (e.g. foo^2 or title:bar^4)
    • [x] Fixed inability to use leading wildcards (e.g. *foo or *title:bar)
    • [x] Fixed theme-color meta tag getting out-of-sync in https://github.com/squidfunk/mkdocs-material/commit/944180d572ac6aab03f12e8c444f92f6c3bd0f33
    • [x] Fixed prev/next page keyboard navigation when footer is not present in 763423d30
    • [x] Fixed overflowing navigation tabs not being scrollable in 9fb36102
    • [x] 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.

    announcement 
    opened by squidfunk 35
Releases(9.0.0b4)
  • 9.0.0b4(Dec 11, 2022)

    Note: this is a beta release – see #4714

    • Improved readability of search sharing link
    • Fixed search highlighting of occurrences found in tags
    • Fixed search sharing link 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)
    Source code(tar.gz)
    Source code(zip)
  • 9.0.0b3(Dec 8, 2022)

    Note: this is a beta release – see #4714

    • Fixed #4713: Mermaid sequence diagram numbers unreadable in dark mode
    • Fixed #4718: Fixed not enough values to unpack error in search plugin
    • Fixed table of contents title not showing
    Source code(tar.gz)
    Source code(zip)
  • 9.0.0b2(Dec 7, 2022)

  • 9.0.0b1(Dec 7, 2022)

    Note: this is a beta release – see #4714

    • Rewrite of search plugin with support for rich previews
    • Added support for search tokenizer lookahead
    • Added support for advanced search highlighting
    • Added support for excluding content from search
    • Added support for configurable search pipeline
    • Added native support for offline search via offline plugin
    • Omit code block line numbers from search
    • Improved stability of search plugin when using --dirtyreload
    • Removed support for prebuilding search indexes
    • Removed support for indexing only titles in search
    • Fixed detection of composition events in search interface
    • Fixed search plugin not using title set via front matter
    • 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
    • Added material namespace to plugins and updated to MkDocs 1.4.1 fee799a759a947a68714a59d0279cf8c77eb134a
    • Added support for multiple instances of built-in tags plugin 17186b49478e4ea17b1ede882c61439d8d4d8d1b
    • Added support for removing copy-to-clipboard button in 128e26742
    • Added support for removing footer navigation in 8fdd1ad52
    • Updated to MkDocs 1.4.2 in 17186b49478e4ea17b1ede882c61439d8d4d8d1b
    • Updated Norwegian translations (via #4647)
    • Fixed Korean language code (~~kr~~ ko) in 5aebaaa71
    Source code(tar.gz)
    Source code(zip)
  • 8.5.11(Nov 30, 2022)

  • 8.5.10(Nov 11, 2022)

  • 8.5.9(Nov 8, 2022)

  • 8.5.8(Nov 3, 2022)

    • Added support for always showing settings in cookie consent
    • Fixed #4571: Buttons invisible if primary color is white or black
    • Fixed #4517: Illegible note in sequence diagram when using slate scheme
    Source code(tar.gz)
    Source code(zip)
  • 8.5.7(Oct 22, 2022)

  • 8.5.6(Oct 2, 2022)

  • 8.5.5(Oct 1, 2022)

  • 8.5.4(Sep 30, 2022)

  • 8.5.3(Sep 20, 2022)

  • 8.5.2(Sep 18, 2022)

    • Updated Mermaid.js to version 9.1.7
    • Fixed overly large headlines in search results (8.5.0 regression)
    • Fixed #4358: Navigation sections appear as clickable (8.5.0 regression)
    • Fixed #4356: GitHub repository statistics fetched before consent
    Source code(tar.gz)
    Source code(zip)
  • 8.5.1(Sep 15, 2022)

  • 8.5.0(Sep 13, 2022)

    • Added support for social cards
    • Added support for code annotation anchor links (deep linking)
    • Added support for code annotation comment stripping (syntax modifier)
    • Added support for sidebars scrolling automatically to active item
    • Added support for anchor following table of contents (= auto scroll)
    • Added support for tag icons
    Source code(tar.gz)
    Source code(zip)
  • 8.4.4(Sep 12, 2022)

  • 8.4.3(Sep 7, 2022)

    • Added Simple Icons to bundled icons (+2,300 icons)
    • Added support for changing edit icon
    • Moved page actions to separate partial (actions.html)
    • Fixed #4291: Version switching doesn't stay on page when anchors are used
    • Fixed #4327: Links in data tables do not receive link styling
    Source code(tar.gz)
    Source code(zip)
  • 8.4.2(Aug 27, 2022)

    • Updated Slovenian translations
    • Fixed #4277: Feedback widget hidden after navigation with instant loading
    • Fixed numeric tags in front matter breaking search functionality
    Source code(tar.gz)
    Source code(zip)
  • 8.4.1(Aug 21, 2022)

  • 8.4.0(Aug 13, 2022)

    • Added support for cookie consent
    • Added support for feedback widget (Was this page helpful?)
    • Added support for dismissable announcement bar
    • Added Armenian, Lithuanian, Tagalog, and Urdu translations
    Source code(tar.gz)
    Source code(zip)
  • 8.4.0rc1(Jul 20, 2022)

    • Added support for cookie consent
    • Added support for feedback widget (Was this page helpful?)
    • Added support for dismissable announcement bar

    Related: #4146

    Source code(tar.gz)
    Source code(zip)
  • 8.3.9(Jul 4, 2022)

    • Updated Taiwanese translations for search
    • Allow ids for content tabs with special characters (for mkdocstrings)
    • Fixed #4083: home not clickable when using versioning (8.3.5 regression)
    Source code(tar.gz)
    Source code(zip)
  • 8.3.8(Jun 24, 2022)

  • 8.3.7(Jun 22, 2022)

  • 8.3.6(Jun 16, 2022)

  • 8.3.5(Jun 14, 2022)

  • 8.3.4(Jun 11, 2022)

  • 8.3.3(Jun 7, 2022)

  • 8.3.2(Jun 5, 2022)

Owner
Martin Donath
After three days without programming, life becomes meaningless
Martin Donath
An MkDocs plugin to export content pages as PDF files

MkDocs PDF Export Plugin An MkDocs plugin to export content pages as PDF files The pdf-export plugin will export all markdown pages in your MkDocs rep

Terry Zhao 266 Dec 13, 2022
An MkDocs plugin that simplifies configuring page titles and their order

MkDocs Awesome Pages Plugin An MkDocs plugin that simplifies configuring page titles and their order The awesome-pages plugin allows you to customize

Lukas Geiter 282 Dec 28, 2022
Generate a single PDF file from MkDocs repository.

PDF Generate Plugin for MkDocs This plugin will generate a single PDF file from your MkDocs repository. This plugin is inspired by MkDocs PDF Export P

null 198 Jan 3, 2023
MkDocs plugin for setting revision date from git per markdown file

mkdocs-git-revision-date-plugin MkDocs plugin that displays the last revision date of the current page of the documentation based on Git. The revision

Terry Zhao 48 Jan 6, 2023
A tool that allows for versioning sites built with mkdocs

mkdocs-versioning mkdocs-versioning is a plugin for mkdocs, a tool designed to create static websites usually for generating project documentation. mk

Zayd Patel 38 Feb 26, 2022
MkDocs Plugin allowing your visitors to *File > Print > Save as PDF* the entire site.

mkdocs-print-site-plugin MkDocs plugin that adds a page to your site combining all pages, allowing your site visitors to File > Print > Save as PDF th

Tim Vink 67 Jan 4, 2023
:blue_book: Automatic documentation from sources, for MkDocs.

mkdocstrings Automatic documentation from sources, for MkDocs. Features - Python handler - Requirements - Installation - Quick usage Features Language

null 1.1k Jan 4, 2023
Yet Another MkDocs Parser

yamp Motivation You want to document your project. You make an effort and write docstrings. You try Sphinx. You think it sucks and it's slow -- I did.

Max Halford 10 May 20, 2022
Dev Centric Tools for Mkdocs Based Documentation

docutools MkDocs Documentation Tools For Developers This repo is providing a set of plugins for mkdocs material compatible documentation. It is meant

Axiros GmbH 14 Sep 10, 2022
Mkdocs obsidian publish - Publish your obsidian vault through a python script

Mkdocs Obsidian Mkdocs Obsidian is an association between a python script and a

Mara 49 Jan 9, 2023
Plugins for MkDocs.

Plugins for MkDocs and Python Markdown pip install neoteroi-mkdocs This package includes the following plugins and extensions: Name Description Type m

null 35 Dec 23, 2022
Sphinx theme for readthedocs.org

Read the Docs Sphinx Theme This Sphinx theme was designed to provide a great reader experience for documentation users on both desktop and mobile devi

Read the Docs 4.3k Dec 31, 2022
Lightweight, configurable Sphinx theme. Now the Sphinx default!

What is Alabaster? Alabaster is a visually (c)lean, responsive, configurable theme for the Sphinx documentation system. It is Python 2+3 compatible. I

Jeff Forcier 670 Dec 19, 2022
Sphinx Bootstrap Theme

Sphinx Bootstrap Theme This Sphinx theme integrates the Bootstrap CSS / JavaScript framework with various layout options, hierarchical menu navigation

Ryan Roemer 584 Nov 16, 2022
My Sublime Text theme

rsms sublime text theme Install: cd path/to/your/sublime/packages git clone https://github.com/rsms/sublime-theme.git rsms-theme You'll also need the

Rasmus 166 Jan 4, 2023
Material for the ros2 crash course

Material for the ros2 crash course

Emmanuel Dean 1 Jan 22, 2022
Grokking the Object Oriented Design Interview

Grokking the Object Oriented Design Interview

Tusamma Sal Sabil 2.6k Jan 8, 2023
Simple yet powerful CAD (Computer Aided Design) library, written with Python.

Py-MADCAD >>> it's time to throw parametric softwares out ! Simple yet powerful CAD (Computer Aided Design) library, written with Python. Installation

jimy byerley 124 Jan 6, 2023
Mkdocs + material + cool stuff

Modern-Python-Doc-Example mkdocs + material + cool stuff Doc is live here Features out of the box amazing good looking website thanks to mkdocs.org an

Francesco Saverio Zuppichini 61 Oct 26, 2022
Replit theme sync; Github theme sync but in Replit.

This is a Replit theme sync, basically meaning that it keeps track of the current time (which may need to be edited later on), and if the time passes morning, afternoon, etc, the theme switches. The idea came from GitHub's theme sync. Except this is a separate program, not attached to Replit.

Glitch 8 Jun 25, 2022