🚀 Material for MkDocs 5.0.0 RC 4

[squidfunk]

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

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

Fixed in RC 2

• Search does not close in 5.0.0 RC 1 #1505: Search does not close – c0abaf5
• Exception when setting only logo icon in 5.0.0rc1 #1503: Exception when setting only logo icon – fcbd47c
• Tabbed content alignment #1502: Tabbed content alignment – 4d386df, 447d409
• Code block styling issues with pymdownx.inline and inline #1499, Fix inline line highlight padding, wrapping, and gutter background #1501: Code block styling issues with pymdownx.inline and inline

Fixed in RC 3

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

Fixed in RC 4

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

Migration

See the migration guide in the deploy preview.

[fkorotkov]

@squidfunk will you publish an RC Docker image as well?

[squidfunk]

@fkorotkov just pushed the Docker image, see OP.

[SM-26]

Hey, I'm having some issues with custom logos/icons.

If I want to use my own PNG/SVG, where should I put it in?

this is my mkdocs.yml:

theme:
  name: material
  custom_dir: 'theme'
  language: en
  feature:
    - instant
    - tabs
  palette:
    primary: 'blue grey'
    accent: 'red'
  # font:
    # text: 'Roboto'
    # code: 'Ubuntu Mono'
  icon:
    logo: "assets/images/android-chrome-256x256.png"
  favicon: "assets/images/safari-pinned-tab.svg"

and in my directory looks like this:

docs
- index.md
- robots.txt
-sitemap.xml
theme
- assets
-- javascripts
-- stylesheets
- icons
-- assets
--- images
---- android-chrome-256x256.png
---- android-chrome-256x256.png.svg
- main.html

but I still get error

raise TemplateNotFound(template)
 jinja2.exceptions.TemplateNotFound: .icons/assets/images/android-chrome-256x256.png.svg
 ERROR: Job failed: exit code 1

Where is ".icons".?

Thanks in advance.

[diba1013]

I followed your migration guide and it seems to work. Great work on the CSS Variables, took a bit of trial and error, but works fine. Need to fine-tune our CI colors now.

---

@SM-26

Where is ".icons"

The icons specified for icon>logo are relative to the .icon directory in the theme:

Please take a look at my migration at https://github.com/retest/docs/tree/feature/mkdocs-material-v5

I specified theme and put them under theme/.icon/retest/logo.svg to be in sync with fontawesome and other icon packs

Edit: notice the . before .icons

[squidfunk]

Note that icons can only be used as SVGs, as they are inlined into the HTML.

I specified theme and put them under theme/.icon/retest/logo.svg to be in sync with fontawesome and other icon packs

Ah, yes! So custom icons can be specified when using theme extension - I haven#t thought of that. We should document that!

[wilhelmer]

So there's theme.logo, which can only be set to your own custom-made logo (png, svg, whatever).

And there's theme.icon.logo, which can only be set to any of the icons bundled with the theme, e.g., material/cloud.

Is that correct? IMHO, that's a bit confusing ...

[squidfunk]

The idea was no unify icon configuration, so that maybe later we can add more icons to the theme.icon namespace that can be configured. I understand that it may be confusing at first. What would be a better approach? From v4 to v5 it currently is:

• theme.logo.icon -> theme.icon.logo
• extra.repo_icon -> theme.icon.repo

[wilhelmer]

Maybe:

• theme.logo.icon -> theme.icon.logo
• extra.repo_icon -> theme.icon.repo
• theme.logo -> theme.icon.custom_logo

[squidfunk]

theme.logo can be any file format

[wilhelmer]

And everything in the theme.icon namespace should be SVG only? Is that a must?

If yes, I don't know – but the difference between theme.logo and theme.icon.logo isn't clear just by looking at the names. Maybe theme.logo -> theme.custom_logo? But the other .logo can be customized too, as we just learned ...

[diba1013]

I agree that there is an inconsistency between theme.logo and theme.icon.logo and I moved the logo to theme.icon.logo because it makes more sense to merge these into one namespace.

But I do not know the code behind that and if the svg locking was done for a reason (e.g. to inline the svgs directly into the html) because otherwise it would have been to complicated or would have resulted in ugly code (e.g. exist check of file, etc).

But the other .logo can be customized too, as we just learned ...

As to update the documentation, it would be helpful to update the documentation and to make it more clear to what I did. Because what I did—in retrospect—seems quite simple, but if you do not have an idea on what I did, it seems complicated.

To elaborate: My solution (I did not check this) works only, because I have an overwritten theme defined. theme.icon.logo looks relative to a specific .icons directory that is only available from the theme. Thus to define theme.icon.logo the way I did, you need to overwrite a theme which is a more advanced topic and may be overkill for many use cases. Whereas theme.logo does not care where the icon is placed and therefore a more straightforwards and simple solution.

[wilhelmer]

Different topic:

In the OP, you mention:

• Improved extensible keyboard handling

Could you elaborate on that, maybe with an example on how to add custom keyboard shortcuts? And maybe also add that to the docs?

[squidfunk]

The point is that theme.icon.logo is inlined and thus needs to be SVG whereas theme.logo is embedded as an img. Maybe we should clarify that in the docs. If somebody has an idea how we could better clarify it, I would be happy to merge PRs.

[squidfunk]

I assume you added the „made with ❤️...“ yourself, so yeah it doubles in your case but normally there’s only the copyright notice and the theme notice.

I’m open to suggestions regarding the wording, but I want to get rid of „powered by“ as that is the wrong message after thinking about it again. And „built with“ is too technical.

[ofek]

@Andre601

https://github.com/facelessuser/pymdown-extensions/blob/1cec43f146cdd41dc9515be03c0bc105e85ae953/mkdocs.yml#L6-L9

[squidfunk]

... also the theme provides much more than just the design. The whole UX.

[Andre601]

@Andre601

https://github.com/facelessuser/pymdown-extensions/blob/1cec43f146cdd41dc9515be03c0bc105e85ae953/mkdocs.yml#L6-L9

What are you telling me with this?

@squidfunk What about the other question? Can this be altered using the custom_dir and by providing a own footer.html, or whatever would be responsible? Credits would still be given of course.

[ofek]

You were looking for an example of an override, no?

[Andre601]

You were looking for an example of an override, no?

This doesn't override the "made with ..." text, just fyi

I am more than aware of this... That even inspired me to customize the text color a bit, as the copyright is usually the same color like the Link-color of "Material for MkDocs"

[ofek]

Ah, my bad

[squidfunk]

@Andre601 of course you can adjust it using theme extension – just bring your own partials/footer.html 😊

[Andre601]

@Andre601 of course you can adjust it using theme extension – just bring your own partials/footer.html 😊

Alright. I'll need to look into what I have to actually alter, to not mess stuff up... Sure will be fun... I-I hope

[squidfunk]

@Andre601 https://squidfunk.github.io/mkdocs-material/customization/#extending-the-theme - the docs describe exactly the overriding of the footer 😉

[Andre601]

👍

https://github.com/purrbot-site/Docs/blob/feature/footer-customisation/override/main.html

[facelessuser]

@Andre601 Think you meant Built instead of Build?

[Andre601]

@Andre601 Think you meant Built instead of Build?

Not a pro with English grammar...

[ofek]

@facelessuser For the instant feature and loading of extra JS described here #1498 (comment)

Will v7 automatically handle that for the new UML library?

• https://facelessuser.github.io/pymdown-extensions/extensions/superfences/#custom-fences
• https://facelessuser.github.io/pymdown-extensions/extensions/superfences/#uml-diagram-example

Mermaid looks absolutely beautiful btw 😄

[facelessuser]

@facelessuser For the instant feature and loading of extra JS described here #1498 (comment)

@ofek v7 of pymdownx doesn't provide any JS automatically. It didn't automatically provide JS for the old UML either. UML examples are exactly that, examples of how SuperFences can be expanded.

With that said, what I have I believe works with instant (last I checked as I don't currently run instant). I added the "switch" event in my own "extra JS": https://github.com/facelessuser/pymdown-extensions/blob/master/docs/src/js/extra.js#L7.

I don't have a solution yet for MathJax loading in the traditional way, but as I only need it on one page, I currently include it at the end of my Arithmatex page, and it seems to work fine. As I'm not running instant by default, I haven't looked into getting it working in the more traditional way that people would normally load it.

Mermaid looks absolutely beautiful btw 😄

Thanks! I really wanted it to kind of go with the overall theme I had going on in the docs, I think it turned out pretty good 🙂.

Mermaid, annoyingly, no longer release CSS, and instead opt to inline the CSS in the exported SVG. So, I include the source in the build process, import their SCSS, and build my own with my own colors and some style overrides. Then we configure Mermaid to not load an inline CSS, and then include our own 😉 .

I think Mermaid provides way more, and seems quite active. The old Sequence Diagram that I used to use works, but I think is pretty much dead, and the latest isn't really compatible with the latest Flowchart.js.

Anyways, I find Mermaid more powerful despite its quirks here and there, and I've seen a number of people preferred it over the old suggestions, so I thought I'd run with it.

[facelessuser]

By the way, I use a custom loader for Mermaid to overcome some issues with loading diagrams from hidden tabs and details elements. I mention that in the docs as well.

[wilhelmer]

In v4, if you started searching before search_index.json was loaded, search results were displayed as soon as the index had been loaded.

In v5, if you start searching before the index is loaded, the search displays "No matching results" and keeps displaying that message even after the index has been loaded.

For example, if you type "test" and wait until the search index is loaded, Material keeps displaying "No matching results" until you press a key. You must change the search term to, e.g., "tes" and then back to "test" to get your search results.

Steps to reproduce:

1. Visit https://docs.baslerweb.com
2. Enable DevTools
3. Disable cache and throttle to Fast 3G or slower
4. Page refresh
5. Start searching for "test" immediately

[squidfunk]

@wilhelmer could you open an issue? I don’t consider it blocking for the release tomorrow but we should definitely fix it.

[wilhelmer]

Yep, will do. And agree, please don't block the release, as this will only affect projects with large search indexes (like ours).

[squidfunk]

It’s actually related to the issue that proposes the introduction of a loader during index time, #1439.

[wilhelmer]

Should I add a comment there or would you rather keep it as two separate issues?

[squidfunk]

I‘d say the open issue is sufficient, so add a comment there regarding the behavior you described.

[squidfunk]

It's done! 🎉🎉🎉 Material for MkDocs 5 is out!

A big THANK YOU to all of you guys testing, reporting bugs, improving it! Without your extensive testing, we wouldn't have such a stable release!

[ofek]

Thank you!!!

[lgeiger]

Congrats on v5!

this is a limitation of instant loading as we cannot possibly know which scripts must be executed again after a document switch, except those contained in the article (using script directly from Markdown). There is however an event to which you can listen on window called DOMContentSwitch which is emitted after the content was replaced. You could load MathJax once and then trigger the rendering in this event listener.

Thanks for the help. This solution works very well.
For MathJax 3 simply adding the following few lines makes it work smoothly with instant loading:

// Re-render MathJax on document switch (instant loading, custom event)
document.addEventListener("DOMContentSwitch", function() {
  MathJax.typesetPromise();
});