🚀 Material for MkDocs 5.0.0 RC 4 #1498

Closed squidfunk closed 4 years ago

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.

@rohancragg thanks for reporting! Fixed the docs in 2cc06859.

I found that I had to make the following change to my PIP requirements.txt:

pymdown-extensions>=7.0b2
mkdocs-material>=5.0.0rc4

RC 4 has the correct version of Pymdown as a dependency, so no need to specify it. A compatible version is always included with the theme.

RC 4 has the correct version of Pymdown as a dependency, so no need to specify it. A compatible version is always included with the theme.

OK, thanks, it's probably just because I'd been specifying it and didn't need to

I had to remove the reference to - pymdownx.superfences in my mkdocs.yml

You might want to add that to the upgrade steps.

pymdownx.superfences should continue to work.

RC 4 has the correct version of Pymdown as a dependency, so no need to specify it. A compatible version is always included with the theme.

Good to know.

It's also mentioned in the new docs – I have removed all installation instructions for packages that are bundled anyway (even MkDocs!) 😀For Pymdown it makes sense to let the theme select the supported version. Also, @facelessuser, the author of Pymdown Extensions, is very responsive, so the package will almost likely almost be up-to-date.

yup, SuperFences 100% works. All of it works with Material, though not everything pymdown-extensions does is directly supported with styling, but most like 99%.

pymdownx.superfences should continue to work.

If I don't remove it get this warning on mkdocs build:

[~]\scoop\apps\python\3.8.2\lib\site-packages\pymdownx\superfences.py:634: PymdownxDeprecationWarning:
The tab option in SuperFences has been deprecated in favor of the general purpose 'pymdownx.tabbed' extension.
While you can continue to use this feature for now, it will be removed in the future.
Also be mindful of the class changes, if you require old style classes, please enable the 'legacy_tab_classes' option.

  warnings.warn(MSG_TAB_DEPRECATION, PymdownxDeprecationWarning)

is this perhaps because I've enabled this:

features:
    - tabs
    - instant

It says the [tab option] (https://facelessuser.github.io/pymdown-extensions/extensions/superfences/#tabbed-fences) has been deprecated in SuperFences, not that SuperFences is deprecated. Moving forward, people should use the general Tabbed extension to do tabbed code, but during the transition period, you can still use SuperFences' tab option, but it'll warn you that one day it won't work, so it is probably better to use the general extension some time soon to prevent bring caught unawares.

@facelessuser - thanks, yes, I've now removed all use of tabbed fences and the warning goes away!

Is it intentional, that Material Theme now omits the link to MkDocs rather than adding its own link to the footer? (made with <Material for MkDocs> instead of powered by <MkDocs> and <Material for MkDocs> (<> mean that those words have links))

Also, no expert on english grammar so perhaps a stupid question, but why is it lowercase at the beginning and not Uppercase (made/powered instead of Made/Powered)

Yes. That's an intentional change. It reduces the clutter in the footer. Before, MkDocs was the first link, so people go to the MkDocs page with no Material theme whatsoever. Since Material "brings its own MkDocs" (as a requirement), there's no need to link to MkDocs itself. The docs now also don't include MkDocs installation instructions, as it's automatically installed with the theme.

Just trying to be less confusing.

I thought about making it uppercase, you're probably right.

In response to the footer (again): Wouldn't it make a bit more sense to change it to something like "Design provided by Material for MkDocs"?

Because it looks a bit weird when you have a text like the following one and there is a second "Made with ..." text footer

But I assume I could alter the footer text somehow (through override?)

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.

@Andre601

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

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

@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.

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

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"

Ah, my bad

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

@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

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

👍

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

@Andre601 Think you meant Built instead of Build?

@Andre601 Think you meant Built instead of Build?

Not a pro with English grammar...

@facelessuser For the instant feature and loading of extra JS described here https://github.com/squidfunk/mkdocs-material/issues/1498#issuecomment-601020251

Will v7 automatically handle that for the new UML library?

Mermaid looks absolutely beautiful btw 😄

@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.

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.

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:

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

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

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

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

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

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

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!

Thank you!!!

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();
});

squidfunk / mkdocs-material