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

@BigIve you have to distinguish two things here - mkdocs and mkdocs-material. I assume you updated to the release candidate of Material for MkDocs 5 which is a theme for MkDocs and requires version 1.1 of MkDocs. If you were running version 4.x of mkdocs-material before, the error may come from stale dependencies due to pips aweful dependency management. My theory is that mkdocs wasn't updated to 1.1 and you're still running 1.0. Try to force-reinstall everything (incl. dependencies) with the following command:
pip install --upgrade --force-reinstall "mkdocs-material>=5.0.0rc2"
EDIT: I just realized that the error originates in the mkdocs_git_revision_date_plugin you're using:
...
 File "c:\program files (x86)\python38-32\lib\site-packages\mkdocs_git_revision_date_plugin\plugin.py", line 6, in <module>
    from mkdocs.utils import string_types
ImportError: cannot import name 'string_types' from 'mkdocs.utils' (c:\program files (x86)\python38-32\lib\site-packages\mkdocs\utils\__init__.py)
Thus, the error may be related to the plugin, not this theme. If the reinstallation doesn't help, you may contact the authors of the plugin.

Hi squidfunk, I've tried the command you suggested and am still getting the same error as before.

I've also tried a command I was given to update that date plugin but it doesn't seem to help either.

If I comment out that plugin what functionality will I loose? Just thinking of doing it as a test.

Thanks for the assistance so far.

I can see an 'issue' on the page for that plugin that seems to acknowledge this error and leads to this page where they mention a fix for the file. https://github.com/zhaoterryy/mkdocs-git-revision-date-plugin/pull/13/files However I've tried to re-install and force install the plugin again, and even make a new clone of the repository and the file doesn't seem to be brought down to my PC. Am very confused.

@BigIve I'm using mkdocs-git-revision-date-localized-plugin, they fixed that https://github.com/timvink/mkdocs-git-revision-date-localized-plugin/issues/8

pip install "mkdocs-git-revision-date-localized-plugin>=0.4.6"

@ofek Thanks for the command line. I ran it and it did seem to take a while to install. However the file in question hasn't change and the same error as before is still present.

@BigIve https://squidfunk.github.io/mkdocs-material/plugins/revision-date/

I noticed the new tabbed extension changed

5.0.0b2.post1:

Capture

5.0.0rc2:

Capture

That new underline of the current tab is awesome!!! Can we add the outline back though? There is no way to tell where it ends

@BigIve https://squidfunk.github.io/mkdocs-material/plugins/revision-date/

@ofek - Thanks for that. I double checked my plugins list and hadn't correctly changed the one for the date plugin. So after correcting it some good news. The above error no longer occurs.

The annoying news is that I now get another error. As far as I know I haven't changed the lightgallery extension, or is that affected by the change to the mkdocs theme etc? --------------------------------------------------------------------------------- PS C:\GitHub\MS-Cloud-Doco> mkdocs gh-deploy ERROR - Config value: 'markdown_extensions'. Error: Failed loading extension "lightgallery".

Aborted with 1 Configuration Errors! PS C:\GitHub\MS-Cloud-Doco> ---------------------------------------------------------------------------------

@BigIve I would suggest to move this discussion somewhere else as this is very likely related to your setup as opposed to the latest version of this project. A general support forum like StackOverflow might be a good place to get some help.

@ofek the new tabs styling will not receive a border by default. The reason for this is that you can now use tabs in other contexts like Admonitions or Details blocks and I’d like to leave some room for additional customization. If you want to add the borders back, a little extra CSS should be sufficient. Just add some padding on .tabbed-content and a border on .tabbed-set to your liking and you should be good to go.

@BigIve I would suggest to move this discussion somewhere else as this is very likely related to your setup as opposed to the latest version of this project. A general support forum like StackOverflow might be a good place to get some help.

@squidfunk - Just tried a re-install of the lightbox extension. And I can once again deploy my mkdocs pages... yay.

Now that I can once again deploy, I'd like to ask about the 'tabbed' feature that was discussed by @ofek above. Looking it up it seems really cool. How do I activate it, Is it part of the new mkdocs that I installed today? Or is it a seperate plugin?

I've tried following the formatting instructions in the link below but the 'tabs' are not recognised when the page is deployed.

https://deploy-preview-1486--mkdocs-material-preview.netlify.com/extensions/pymdown/#tabbed

@BigIve you probably forgot to configure it:

markdown_extensions:
  - pymdownx.tabbed

I can again just stress to read the docs on the features you want to use. Everything is documented in there. If you follow the docs closely, it should work as expected.

Ah, that makes sense. Do you have an example CSS block from before? CSS eludes me...

@ofek, well for starters you could try:

.md-typeset .tabbed-set {
  border: 1px solid #eee;
}
.md-typeset .tabbed-content {
  padding: 0 1em;
}

Please remember that this theme does try to provide reasonable default styles. However, there may be things that don't fit your use case entirely. For this reason, you can easily add some extra styles that give you the desired behavior. What we cannot do is provide everything in parallel through options or whatever. That's just not possible.

@BigIve you probably forgot to configure it:
markdown_extensions:
  - pymdownx.tabbed
I can again just stress to read the docs on the features you want to use. Everything is documented in there. If you follow the docs closely, it should work as expected.

@squidfunk Yes, I double checked that I had included it as you showed (and it is). However, even after doing that I see a 'radio button' each time the formatting for the 'tab' is used.

@BigIve If it doesn't work, it's almost certainly some problem with your setup. It works for everyone else. I'm sorry but we have to cut the discussion here. Please post your question on StackOverflow or try the official Gitter channel, maybe somebody can help you with your setup. This thread is reserved for problems specific to the RC of version 5.

@BigIve Please post your question on StackOverflow (no need to reply here) if this doesn't work but it's a new feature so run: pip install "pymdown-extensions>=7.0b2"

@squidfunk Thank you!!! FYI changed padding: 0 1em; to padding: 1em 1em; to get extra space at the bottom

It's been a while since 4.x but I recall page refreshes keeping your place. Now F5 takes you to the top (without an anchor selected). Is that intentional?

@ofek, I'm pretty sure that any issues like that may be because instant is enabled. That's still experimental. I assume if you turn that off, all would probably go back to normal.

Yup indeed, that was it! Gonna disable for now

Scroll restoration is a pretty tough nut to crack. Instant loading already covers a lot of cases but there's still some work to be done.

@ofek - actually, could you open an issue for the problem you described? We should document everything that currently breaks with instant loading in issues.

https://github.com/squidfunk/mkdocs-material/issues/1507

Ensures landmarks are unique (probably fixed by role=...?)

Thanks @squidfunk - this is the last remaining accessibility issue to fix on my list!

Trouble is with the <nav class="md-header-nav md-grid"> element. This triggers this issue:

https://dequeuniversity.com/rules/axe/3.5/landmark-unique?application=rocketvalidator

Should I open a new issue for this?

Also, I'll be happy to provide free accounts on the accessibility checker if you want to check directly - ping me at jaime@rocketvalidator.com and I'll set you up.

@jaimeiniesta as I understand we just need to add the role attribute, so you're encouraged to submit a PR. Thanks for the offer regarding the account, maybe I'll come back to it in the future :-) Until then I'll trust your experience.

@jaimeiniesta as I understand we just need to add the role attribute

I think a better fix is using aria-label to describe the different nav elements. I'll submit a PR.

https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/Navigation_Role

PR ready: https://github.com/squidfunk/mkdocs-material/pull/1516

Just released RC 3 on PyPI and DockerHub.

I think RC3 is good to go. Fire it up 🔥

@wilhelmer you mean release the final version? Not just yet. My iteration plan is to wait until the end of March if something else pops up. There are so many changes in there, better be sure 😊 if you’re already using the RC there will be no changes anyway, so the upgrade path should be very smooth unless there’s still something to be changed.

That’s fine. I‘ll use RC3 in production then.

Thanks for the great work on version 5! I am really looking forward to the stable release.

I noticed a small glitch when trying out the release candidate: If experimental instant loading is enabled, extra_javascript is not properly loaded when switching between pages. extra_javascript is only available on first load and disappears after switching to a different page. This is in particular noticeable when using MathJax or plotting libraries to render content which require additional Javascript as rendered content will disappear when switching to a different page and will only appear again after a full reload.

@lgeiger 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. This is already done for Google Analytics:

https://github.com/squidfunk/mkdocs-material/blob/89f39117c01aa4eefe95d23651a3b82cf3088c0c/src/partials/integrations/analytics.html#L51-L54

Ah, that's a bummer. Just tried with https://facelessuser.github.io/pymdown-extensions/extensions/superfences/#custom-fences and indeed it's only rendered if it happens to be on the first loaded page (and even gone when navigating back to it)

Also, just noticed an annoying thing but unsure if it's a regression: any h5 has header text in all caps

#### test4

##### test5

###### test6

Capture

Even the HTML output looks correct too (no caps)

<h4 id=test4>test4<a class=headerlink href=#test4 title="Permanent link">&para;</a></h4> <h5 id=test5>test5<a class=headerlink href=#test5 title="Permanent link">&para;</a></h5> <h6 id=test6>test6<a class=headerlink href=#test6 title="Permanent link">&para;</a></h6>

@ofek the same as for v4, so no regression. You could use some extra CSS to override the default style if you don't like it.

Ah, that's a bummer. Just tried with https://facelessuser.github.io/pymdown-extensions/extensions/superfences/#custom-fences and indeed it's only rendered if it happens to be on the first loaded page (and even gone when navigating back to it)

As noted in my previous comment, it's pretty easy to set it up by re-triggering it with DOMContentSwitch.

Woah yup!

https://github.com/squidfunk/mkdocs-material/blob/dc5d86d52e380fa0ec558a616992143312de0a65/src/assets/stylesheets/base/_typeset.scss#L124-L127

I didn't know CSS could do stuff like that, I wonder how it handles non-ascii...

Since v5 can introduce minor breaking changes, what do you think of removing that capitalization? What was the original intent?

We're in the process of writing an extension (https://github.com/DataDog/mkdocs-click) to auto-generate our CLIs and noticed this for a few subcommands which was extremely unexpected

Since v5 can introduce minor breaking changes, what do you think of removing that capitalization? What was the original intent?

I believe the original intent is distinguishing the header level from others. When the levels get even lower, you can't just keep making them smaller, it is no longer practical. In this case, the attempt to differentiate is performed by capitalizing the text. I'm not saying whether I think it is good or bad, simply that it is.

@facelessuser is right. I’m happy to discuss alternative approaches to distinguish h4-h6.

I'd take anything that doesn't change which characters are displayed. Maybe a lighter bold?

If you want you can draft a proposal which we can discuss, otherwise It’s probably best to leave it as it is 😉

Done! https://github.com/squidfunk/mkdocs-material/issues/1522

I disabled instant loading, but otherwise rc3 is looking great https://datadoghq.dev/integrations-core/

Fantastic work!

Thanks for all the feedback! I'll try to fix some of the outstanding issues (which are not critical) until the final release. The release will take place on April 7. I'll perform the merge in the early afternoon of that day.

I would like to point out, that the link about the custom CSS in the Getting started page - this one here - leads to a broken site, it seems?

Screenshot:

@Andre601 thanks for pointing it out! Fixed in c4820f93, should be shortly available.

On a side note: the invalid link renders the 404 page, but since the Netlify preview URL doesn't match the site_url, 404 pages are broken. This is local to Netlify and will work correctly in the final deployment.

@wilhelmer c7381103 fixes emissions of keyboard events when in editable elements (input, etc.), i.e. Material will do the check you did manually in https://github.com/squidfunk/mkdocs-material/issues/1498#issuecomment-598275325 for you.

Thanks for the fix and the release announcement.

If you had to publish a documentation project on April 1st (no joke) and wanted to use Material v5, would you use RC3 or the latest version from the rxjs-typescript branch?

I think it's probably safest to use RC3 for now, although it has some very minor bugs. Nevertheless, I think publishing something on April 1 is never a good idea 😉That's also why I moved the release date to April 7, as Tuesdays should be the best weekday for releases and March 31 might already be April 1 in some timezones.

squidfunk / mkdocs-material