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

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

@fkorotkov just pushed the Docker image, see OP.

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.

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

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!

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

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

Maybe:

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

theme.logo can be any file format

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

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.

Different topic:

In the OP, you mention:

[x] 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?

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.

@wilhelmer the docs on extensibility still need to be written, but in general you can subscribe to the keyboard with __material.keyboard$.subscribe(console.log). Maybe we could add some tutorials before the release. Is there something specific you want to achieve?

Let’s say I want to map the t key to toggle the visibility of #myDiv.

Congratulations, the upgraded template looks great! I'm evaluating different alternatives to document our project and trying to pick the most accessible template. MkDocs is the best I've found by now.

In case it helps, here's a report on the new template:

https://rocketvalidator.com/s/159ab862-2423-47ca-8772-27db5565cc73/p

And here is one on the previous version:

https://rocketvalidator.com/s/323579ea-0149-4494-92c6-e40184e4df8a/p

There's a new a11y issue on the new template, ensure that scrollable region has keyboard access.

@wilhelmer the keyboard$ observable emits the following format:

{
  mode: "global" | "search",
  type: "t",
  claim: [Function]
}

The mode tells you whether you're in search mode or global mode (search is inactive). The keyboard observable will filter out all keys that have been pressed in conjunction with shift and control keys (or command on macOS) and put the actual key in type. claim will call ev.preventDefault on the original event to "claim" the key. So, with this knowledge you could achieve what you asked for with:

__material.keyboard$.subscribe(key => {
  if (key.mode === "global" && key.type === "f") {
    var el = document.getElementById("myDiv")
    el.hidden = !el.hidden
    key.claim()
  }
})

@jaimeiniesta thanks for reporting. I can't really make anything out of the report actually, it doesn't say where the actual error is. It only says:

Ensure that scrollable region has keyboard access

<code>

It would be amazing if you could help fixing the errors in a PR, so we could include it in the next RC.

EDIT: okay, I think I know what this is about. The error is specific to the migration guide for version 5 and there are code blocks with long lines (the HTML template diffs). It seems that the validator complains that the code block is not focusable so the user can scroll it with arrows (right?), but this would mean that we would have to set tabindex=0 on all code blocks, because we don't know when it scrolls and when not, as this depends on the display width.

Furthermore, Python Markdown doesn't support setting arbitrary attributes on code blocks, so tabindex would have to be set via JavaScript, which you can easily do yourself if you'd like to fix it:

document.getElementsByTagName("code").forEach(function (el) { el.tabIndex = 0 })

The other errors are related to hacks, e.g. setting autocomplete on the checkbox which toggles the drawer, so the drawer is not open when a user uses the browser history etc.

@wilhelmer the keyboard$ observable emits the following format:
{
  mode: "global" | "search",
  type: "t",
  claim: [Function]
}
The mode tells you whether you're in search mode or global mode (search is inactive). The keyboard observable will filter out all keys that have been pressed in conjunction with shift and control keys (or command on macOS) and put the actual key in type. claim will call ev.preventDefault on the original event to "claim" the key. So, with this knowledge you could achieve what you asked for with:
__material.keyboard$.subscribe(key => {
  if (key.mode === "global" && key.type === "f") {
    var el = document.getElementById("myDiv")
    el.hidden = !el.hidden
    key.claim()
  }
})

Thanks. Global mode doesn't seem to check for editable elements, so I'd add something like

// Skip editable elements
if ((document.activeElement instanceof HTMLElement && document.activeElement.isContentEditable) || document.activeElement.tagName === "TEXTAREA" || document.activeElement.tagName === "INPUT")
    return;

That's true. Actually, for the included keyboard handlers it does, but I didn't want to impose the checking onto the user when customizing. The checking is done here.

https://github.com/squidfunk/mkdocs-material/blob/c0abaf5692126cb57c8e12dfcfd95a1d37246ab7/src/assets/javascripts/integrations/keyboard/index.ts#L151-L162

... and implemented here:

https://github.com/squidfunk/mkdocs-material/blob/c0abaf5692126cb57c8e12dfcfd95a1d37246ab7/src/assets/javascripts/browser/keyboard/index.ts#L49-L62

Just released RC 2 which includes fixes for the reported issues. Updated the OP.

@squidfunk my 2 cents! You can also try with the free Chrome extension for axe on specific pages:

https://www.deque.com/axe/

I'm considering using MkDocs for our own API docs so yes I'll be happy to contribute with PRs to fix the issues I find.

@jaimeiniesta great, however as discussed, some issues are not fixable by this project as they're more related to the Markdown parser or extensions used. Skimming through the report what I would regard as fixable is:

[ ] Ensures landmarks are unique (probably fixed by role=...?)
[ ] All page content must be contained by landmarks (we could set a semantic tag on the hero)
[ ] Elements must have sufficient color contrast (easily fixable by custom CSS if desired)

@squidfunk thanks, I see, I'll mute the non-fixable issues as they're out of scope and concentrate on what can be fixed now. 👍

In 6daac21f6582f2cc474f2fbd199b82b865589b2f, you added hyphens: auto to the main text content:

https://github.com/squidfunk/mkdocs-material/blob/6daac21f6582f2cc474f2fbd199b82b865589b2f/src/assets/stylesheets/base/_typeset.scss#L58-L64

Not sure if the majority of users will like this change. I personally don't.

Just checked www.nytimes.com, www.cnn.com and some major German news sites, none of them use hyphenation for their articles.

@wilhelmer that’s correct. I personally like it because it increases readability. However to disable you can use the following extra CSS:

.md-typeset {
  hyphens: initial;
}

Yes I know, and that's what I did. I just assume users won't be happy with the default.

I'd say the fact that all major news sites don't have auto hyphens enabled is a strong indication that it does not improve readability. Especially the NY Times is very keen on readability.

Let’s wait and see how the general feedback is 😉

I'd prefer to have hyphenation turned off by default as it poses some accessibility problems for people with cognitive impairments or low vision:

https://w3c.github.io/low-vision-a11y-tf/requirements.html#hyphenation

If hyphenation is used, a mechanism to allow the user to turn it off should be present, so the best option I think is to not use it.

Thanks for your feedback. There is an easy mechanism - using extra CSS. It’s takes 5min to set up 😊

What's the hyphen talk about? Screenshot?

Just check the deploy preview linked in the OP

I looked but don't see anything of note...

Just installed the updated mkdocs, I can now no successfully deploy my github repo. How can I roll back this update? I'm new to the world of GitHub and am having a very frustrating time of it. Please advise ASAP.

@BigIve could you give us some more information on what you’re tying to achieve and what error you’re facing?

I looked but don't see anything of note...

FA81D1E2-58D3-4E1D-BB6F-3069195B0E58

Hi, Ever since I tried to update to the new mkdocs I get the following (see below) when I try to run the 'deploy' command. Do some further reading it seems that the newer version doesn't support 'string_types' and this seems to be used quite a bit in the mkdocs currently installed. Unless there is a fix that a 'noob' can do I'd really like to know how to roll back to the earlier version. As I have a lot of work that I need to do to my documentation repo and can't do anything currently.

PS C:\GitHub\MS-Cloud-Doco> mkdocs gh-deploy
Traceback (most recent call last):
  File "c:\program files (x86)\python38-32\lib\runpy.py", line 193, in _run_module_as_main
    return _run_code(code, main_globals, None,
  File "c:\program files (x86)\python38-32\lib\runpy.py", line 86, in _run_code
    exec(code, run_globals)
  File "C:\Program Files (x86)\Python38-32\Scripts\mkdocs.exe\__main__.py", line 7, in <module>
  File "c:\program files (x86)\python38-32\lib\site-packages\click\core.py", line 829, in __call__
    return self.main(*args, **kwargs)
  File "c:\program files (x86)\python38-32\lib\site-packages\click\core.py", line 782, in main
    rv = self.invoke(ctx)
  File "c:\program files (x86)\python38-32\lib\site-packages\click\core.py", line 1259, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "c:\program files (x86)\python38-32\lib\site-packages\click\core.py", line 1066, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "c:\program files (x86)\python38-32\lib\site-packages\click\core.py", line 610, in invoke
    return callback(*args, **kwargs)
  File "c:\program files (x86)\python38-32\lib\site-packages\mkdocs\__main__.py", line 178, in gh_deploy_command
    cfg = config.load_config(
  File "c:\program files (x86)\python38-32\lib\site-packages\mkdocs\config\base.py", line 197, in load_config
    errors, warnings = cfg.validate()
  File "c:\program files (x86)\python38-32\lib\site-packages\mkdocs\config\base.py", line 107, in validate
    run_failed, run_warnings = self._validate()
  File "c:\program files (x86)\python38-32\lib\site-packages\mkdocs\config\base.py", line 62, in _validate
    self[key] = config_option.validate(value)
  File "c:\program files (x86)\python38-32\lib\site-packages\mkdocs\config\config_options.py", line 130, in validate
    return self.run_validation(value)
  File "c:\program files (x86)\python38-32\lib\site-packages\mkdocs\config\config_options.py", line 591, in run_validation
    plgins[item] = self.load_plugin(item, cfg)
  File "c:\program files (x86)\python38-32\lib\site-packages\mkdocs\config\config_options.py", line 599, in load_plugin
    Plugin = self.installed_plugins[name].load()
  File "c:\program files (x86)\python38-32\lib\site-packages\pkg_resources\__init__.py", line 2443, in load
    return self.resolve()
  File "c:\program files (x86)\python38-32\lib\site-packages\pkg_resources\__init__.py", line 2449, in resolve
    module = __import__(self.module_name, fromlist=['__name__'], level=0)
  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)

EDIT: formatted by @squidfunk for better readability.

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

@wilhelmer Oh my, thanks for the heads-up! We have a few folks with vision impairments so we will definitely disable the hyphens. (I also don't like the hyphens fwiw)

Could somebody maybe clarify why hyphenation impacts people with vision impairment?

56bd2b10 reduces the amount of created layers, significantly improving rendering performance.

Before:

After:

Having to follow the broken word to the next line can be hard for people just struggling to read the word. Normally those words don't get broken up.

Just asked one such colleague:

I don't know how it plays with screen readers. So that's a likely issue Personally I haven't thought about this because I don't think I've run into this But off the top of my head I imagine this being annoying when I'm zoomed in and have to go back to the left side of the screen to finish a word

Yeah, my wife became aware that she has a genetic eye disorder, and it has impacted her vision in recent years. I just asked her.

Thanks for the clarification. I find that to be quite astonishing since from my experience nearly all books and magazines use hyphenation.

Thanks for the clarification. I find that to be quite astonishing since from my experience nearly all books and magazines use hyphenation.

My wife does audio books now. She didn't use to, but it's gotten harder for her now. Not everyone does things that are friendly to visually impaired.

I see. Okay then, reverted hyphens in bcb8b4a.

Hmm, upgrade broke tabs

5.0.0b2.post1: https://datadoghq.dev/integrations-core/

5.0.0rc2:

Capture

@ofek RC2 has a deploy preview with working tabs: https://deploy-preview-1486--mkdocs-material-preview.netlify.com/. Did you configure it correctly? Feature configuration has changed from 4.X.X series.

Ah thanks, I had

  feature:
    instant: true
    tabs: true

vs

  features:
    - tabs
    - instant

squidfunk / mkdocs-material