Mkdocs-material: 🚀 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

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

[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:
``` 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:

• [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?

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

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

[wilhelmer]

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

[jaimeiniesta]

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.

[squidfunk]

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

[squidfunk]

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

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

[squidfunk]

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

[squidfunk]

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

[jaimeiniesta]

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

[squidfunk]

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

[jaimeiniesta]

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

[wilhelmer]

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.

[squidfunk]

@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;
}

[wilhelmer]

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.

[squidfunk]

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

[jaimeiniesta]

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.

[squidfunk]

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

[ofek]

What's the hyphen talk about? Screenshot?

[squidfunk]

Just check the deploy preview linked in the OP

[ofek]

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

[BigIve]

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.

[squidfunk]

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

[wilhelmer]

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

[BigIve]

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.

[squidfunk]

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

[ofek]

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

[squidfunk]

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

[squidfunk]

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

Before:

After:

[facelessuser]

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.

[ofek]

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

[facelessuser]

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.

[squidfunk]

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

[facelessuser]

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.

[squidfunk]

I see. Okay then, reverted hyphens in bcb8b4a.

[ofek]

Hmm, upgrade broke tabs

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

5.0.0rc2:

[facelessuser]

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

[ofek]

Ah thanks, I had

  feature:
    instant: true
    tabs: true

vs

  features:
    - tabs
    - instant

[BigIve]

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

[BigIve]

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.

[ofek]

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

[BigIve]

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

[ofek]

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

[ofek]

I noticed the new tabbed extension changed

5.0.0b2.post1:

5.0.0rc2:

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]

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

---

[squidfunk]

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

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

@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

[squidfunk]

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

[ofek]

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

[squidfunk]

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

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

[squidfunk]

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

[ofek]

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

[ofek]

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

[ofek]

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?

[facelessuser]

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

[ofek]

Yup indeed, that was it! Gonna disable for now

[squidfunk]

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.

[squidfunk]

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

[ofek]

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

[jaimeiniesta]

• 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 [email protected] and I'll set you up.

[squidfunk]

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

@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

[jaimeiniesta]

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

[squidfunk]

Just released RC 3 on PyPI and DockerHub.

[wilhelmer]

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

[squidfunk]

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

[wilhelmer]

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

[lgeiger]

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.

[squidfunk]

@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

[ofek]

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)

[ofek]

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

#### test4

##### test5

###### test6

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>

[squidfunk]

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

[squidfunk]

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.

[ofek]

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

[facelessuser]

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.

[squidfunk]

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

[ofek]

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

[squidfunk]

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

[ofek]

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

[ofek]

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

Fantastic work!

[squidfunk]

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.

[Andre601]

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:

[squidfunk]

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

[squidfunk]

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

[wilhelmer]

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?

[squidfunk]

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.

[lazka]

Using 5.0.0rc3 the build fails when using social links:

Traceback (most recent call last):
  File "/home/lazka/.local/bin/mkdocs", line 10, in <module>
    sys.exit(cli())
  File "/home/lazka/.local/lib/python3.8/site-packages/click/core.py", line 829, in __call__
    return self.main(*args, **kwargs)
  File "/home/lazka/.local/lib/python3.8/site-packages/click/core.py", line 782, in main
    rv = self.invoke(ctx)
  File "/home/lazka/.local/lib/python3.8/site-packages/click/core.py", line 1259, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/home/lazka/.local/lib/python3.8/site-packages/click/core.py", line 1066, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/home/lazka/.local/lib/python3.8/site-packages/click/core.py", line 610, in invoke
    return callback(*args, **kwargs)
  File "/home/lazka/.local/lib/python3.8/site-packages/mkdocs/__main__.py", line 159, in build_command
    build.build(config.load_config(**kwargs), dirty=not clean)
  File "/home/lazka/.local/lib/python3.8/site-packages/mkdocs/commands/build.py", line 288, in build
    _build_theme_template(template, env, files, config, nav)
  File "/home/lazka/.local/lib/python3.8/site-packages/mkdocs/commands/build.py", line 114, in _build_theme_template
    output = _build_template(template_name, template, files, config, nav)
  File "/home/lazka/.local/lib/python3.8/site-packages/mkdocs/commands/build.py", line 93, in _build_template
    output = template.render(context)
  File "/home/lazka/.local/lib/python3.8/site-packages/jinja2/environment.py", line 1090, in render
    self.environment.handle_exception()
  File "/home/lazka/.local/lib/python3.8/site-packages/jinja2/environment.py", line 832, in handle_exception
    reraise(*rewrite_traceback_stack(source=source))
  File "/home/lazka/.local/lib/python3.8/site-packages/jinja2/_compat.py", line 28, in reraise
    raise value.with_traceback(tb)
  File "/home/lazka/.local/lib/python3.8/site-packages/material/404.html", line 4, in top-level template code
    {% extends "base.html" %}
  File "/home/lazka/.local/lib/python3.8/site-packages/material/base.html", line 172, in top-level template code
    {% block footer %}
  File "/home/lazka/.local/lib/python3.8/site-packages/material/base.html", line 173, in block "footer"
    {% include "partials/footer.html" %}
  File "/home/lazka/.local/lib/python3.8/site-packages/material/partials/footer.html", line 59, in top-level template code
    {% include "partials/social.html" %}
  File "/home/lazka/.local/lib/python3.8/site-packages/material/partials/social.html", line 10, in top-level template code
    {% include ".icons/" ~ social.icon ~ ".svg" %}
  File "/home/lazka/.local/lib/python3.8/site-packages/jinja2/loaders.py", line 199, in get_source
    raise TemplateNotFound(template)
jinja2.exceptions.TemplateNotFound: .icons/.svg

The error starts once I add the social config from the docs:

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'

[squidfunk]

type was renamed to icon, as stated in the migration guide. The paths did also change. The OP contains the link to the migration guide.

[lazka]

Ah, thanks.

[Andre601]

A suggestion for the icons section of the new guide:
Maybe mention how the names of the different packs are?
I mean you mention material and fontawesome, but what would be the "prefix" for octicons? Just octicons, or something else?

And not sure how important this would actually be for this theme, but perhaps mention that yiz can alter the edit-uri by providing edit_uri in the mkdocs.yml? I myself had a hard time finding this anywhere and only found it through luck... But I guess this is more the job of the actual mkdocs documentation? Nvm I'm actually blind

[squidfunk]

I‘m open to PRs improving the docs, especially on migration. It’s even better coming from actual users than me.

However, as you would have to look up the name of the icon anyway, my idea was that stating the name of the folder where those icons reside was probably enough. We can’t list all of the 5k icons, obviously.

[Andre601]

We can’t list all of the 5k icons, obviously.

My point was, that it should at least mention the how I called it "prefix" (i.e. fontawesome) as it's not 100% sure for people where to look for the icons.

And a unrelated question, but still about the new theme version:
Did something change in terms of custom CSS?
It seems that the codehilite colours for code blocks no longer seems to apply properly as they did for the dark theme CSS I used with the stable release.

I use the dark Theme CSS file from henrywhitake3

Stable version:

5.0.0 RC3

[squidfunk]

Unfortunately we cannot provide support for downstream projects. Some styling (i.e. selectors) changed for code highlighting, so yes, it might be related to that. It’s probably best to create an issue on the respective repository.

[Andre601]

found the problem: codehilite changed to highlight it seems.

[squidfunk]

Both highlighting extensions are supported as in 4.x, so no change on that front. Depends on whether you use pymdownx.highlight or codehilite in mkdocs.yml.

[Andre601]

I use the codehilite one, which makes this even more interesting/weird.
I'll open an issue on the repo of the dark theme to suggest an alternative css file supporting the highlight option.

[squidfunk]

@facelessuser any ideas what could be causing this?

[facelessuser]

@squidfunk, just curious, I noticed that the included Material icons are a mix of official and contributed, I assume it from this collection: https://materialdesignicons.com/. I noticed that some icons have IDs attached to them, for instance I think some of the brand icons in Material (GitHub for instance). Depending on how they are inlined, it could much with other ids. When you insert them via Jinja, do you strip the IDs? I figure when they are set as background or mask-image it shouldn't be a problem. Just something I noticed and am curious about.

[squidfunk]

On a second note: one of the next minor version, most probably 5.1 will include a native dark mode.

[squidfunk]

@facelessuser the icons are extracted from the material-design-icons-svg package which seems to scrape the official site. I included the IDs at some point but removed that again from the Webpack copying logic.

[facelessuser]

@squidfunk @Andre601 SuperFences and InlineHilte use pymdownx.highlight to handle code highlighting, not Codehilite. For a long time they mirrored the settings if you were using CodeHilite, but it still always used pymdownx.highlight.

So in Material 4.X, if you used codehilite, pymdownx.highlgiht would copy over the class name used by codehilite, which is codehilite. But in Material 5.X (which uses pymdownx 7.0 prerelease) does not. pymdownx.highlight uses highlight by default, but you can configure it in pymdownx.highlight, it should work along side codehilite.

[squidfunk]

Thanks for the explanation!

[facelessuser]

@facelessuser the icons are extracted from the material-design-icons-svg package which seems to scrape the official site. I included the IDs at some point but removed that again from the Webpack copying logic.

Cool, so no IDs, good to know :+1:.

[facelessuser]

The big thing you gain from using CodeHilite is indented code block headers with shebangs, and markdown.extensions.fenced_code uses CodeHilite for its highlighting.

    #!python
    import sys

But if you are using pymdownx.superfences you don't really need it:

````

import sys

````

I find no use for CodeHilite, so I no longer try to support anything related to it. I only mirrored the options for a while to transition away from using CodeHilite (which SuperFences used to use a long long time ago).

[facelessuser]

Last post I swear 🙂 . The super short answer:

The referenced dark theme only uses the class codehilite: https://github.com/henrywhitaker3/mkdocs-material-dark-theme/blob/master/site/assets/css/dark-theme-system.css#L153. So you need to use your own with updated classes (highlight) or force pymdownx.highlight to use the class name codehilite.

[squidfunk]

... or wait for 5.1, which should shortly follow after the initial release 😉 probably towards the end of April.

[squidfunk]

I decided to release a last release candidate, as there have been a lot of fixes lately. The final release date will be April 7.

[wilhelmer]

Printing is not working properly for me in Firefox v74.

Steps to reproduce:

1. Set up a minimal project with one fairly long topic (>1 page when printed).
2. Build.
3. Open topic in Firefox 74.
4. File > Print preview.

Result: The print preview shows only one page.

Expected result: The print preview should show all pages needed to print the topic.

Works in Chrome, but not in FF.

[wilhelmer]

Also, __material is no longer defined in RC4? Can't access it from the console either. Did I overlook that change?

[squidfunk]

__material was renamed to app. Does the print problem happen with Firefox and v4?

[wilhelmer]

Thanks. No, does not happen with FF and v4.

[squidfunk]

Confirmed. Could you create a new issue (or PR?)? I guess it has to do with overflow: hidden and flex which should be easy to remove for print styles on body.

https://bugzilla.mozilla.org/show_bug.cgi?id=258397, respectively
https://bugzilla.mozilla.org/show_bug.cgi?id=521204

[lazka]

Instant loading bug (Firefox and Chromium):

• Click on link to trigger instant loading
• History back
• Try to click on the same link again
• Actual: Nothing happens
• Expected: The link works

[squidfunk]

@lazka thanks for reporting! Could you create a new issue, so we can keep track?

[jaimeiniesta]

Awesome! Just deployed our docs and no html/a11y issues were detected this time - except for the muted ones we already discussed. 💪

[Andre601]

I'm not entirely sure if this would be for here, or is better suited for a markdown-expansion like the ones of pymdown, but how about a implementation, to easy add any icon of material, fontawesome or github?
I like that you can use them for social links and other specific places, but I think me and other people would love it, if there was a way to directly put those icons into the text, without requiring this entire <i class="blablabla"> html stuff (keep it very "markdown like" if you will)

A syntax I think would be an idea is perhaps -prefix:icon-?
Like I said, not sure if this is best suited here or better of for a markdown-extension.

[facelessuser]

@Andre601 some ideas for this are already being floated: https://github.com/squidfunk/mkdocs-material/pull/1475.

[Andre601]

A bit unrelated question, but would I just need to use this part here if I want to make a GitHub Action automatically update a page, when a PR was merged on the repo containing the docs?
I am aware that there is a GitHub Action more or less suited for this, but I'm quite sure it doesn't use Material 5.0.0 RC4 and perhaps won't even really support the PyMdown 7 extensions....

[squidfunk]

You could use the workflow as a starting point. From what I read from the MkDocs action, however, it seems to assume a requirements.txt file that is installed, so you could probably specify the versions you want. Haven't tested it, though.

[Andre601]

Is there any way I can force MkDocs/Material to put a single entry in the nav-list to the tabs at the top?
When I f.e. only have - Contribute: contribute.md does it not work.
When I, however, set the following does it work (But it is a bit annoying)

nav:
- Contributing:
  - Contributing: contribute.md

[facelessuser]

I also deploy docs with just this: https://github.com/facelessuser/pymdown-extensions/blob/master/.github/workflows/deploy.yml#L10. I found it just easier to manually do it. Granted, I didn't need all the matrix stuff as I'm only running it on one Python, but I copied and pasted it from other workflows I was doing, so 🤷‍♂ .

[ofek]

Yeah we're doing it manually too https://github.com/DataDog/integrations-core/blob/hack-a-doc/datadog_checks_dev/datadog_checks/dev/tooling/commands/docs/push.py

[facelessuser]

I'm fine with using actions when it is nice a solid and does exactly what I want, but when it doesn't, and it is pretty easy to just manually do it, I usually just do it myself.

[squidfunk]

@Andre601 from the docs:

When tabs are enabled, top-level sections will be rendered in an additional layer directly below the header. The navigation on the left side will only include the pages contained within the selected section. Furthermore, __top-level pages defined inside your project's mkdocs.yml will be grouped under the first tab which will receive the title of the first page.__

You can't put a single entry via mkdocs.yml, as all top-level entries will be grouped under the first tab. Maybe look at mkdocs.yml of the project itself, it should be clearer then:

https://github.com/squidfunk/mkdocs-material/blob/728fef6ec8259e910500885047911c18bae145da/mkdocs.yml#L114-L134

[Andre601]

So tl;dr it's not possible to have it as a separate tab at the top then. Got it.

[squidfunk]

You could always use theme extension and override partials/tabs.html if you'd like more control.

[fkorotkov]

@Andre601 you can take a look at my solution for the issues that I dod for https://cirrus-ci.org to have single pages on top of the page. Here is nav-item partial you can take a look at.

[Andre601]

I'm not really into implementing own HTML files, which is the entire reason I use MkDocs in the first place: To not have to deal with a lot of HTML, CSS and other configuration.
Thanks anyway for the example.

[fkorotkov]

There are minor changes if you'll diff against the original nav-item. But yeah, I feel you 😅

[Andre601]

A bit sad, that there isn't really a main chat for common mkdocs/material questions.
I know that there's a chat on gitter, but it's more about Material and not MkDocs according to the welcome message there, and Stackoverflow is way to unreliable and slow for some small, common questions.
I also don't want to annoy you guys here constantly with such unrelated questions (which also triggers notification for everyone watching this issue 👀)

[ofek]

This looks promising https://github.com/zeit/now/discussions/3874

[squidfunk]

To not have to deal with a lot of HTML, CSS and other configuration.

Unfortunately, it’s impossible to provide a theme that fits everyone’s use case. I understand that you don’t want to go down that path, but you also have to understand that our time is limited, so we have to cut configuration at some point for customization. Funnily, the more configuration options this theme gets, the more users want even more options 😅

A bit sad, that there isn't really a main chat for common mkdocs/material questions.

I think the main problem is that something like this would result in endless requests for customizations, and I think nobody (including me) wants (and can) to do all of this for free.

[Andre601]

I think the main problem is that something like this would result in endless requests for customizations, and I think nobody (including me) wants to do all of this for free.

I don't generally mean about new features here, but rather that there isn't a common chat/place where you could ask all kinds of questions, which aren't always about material or even MkDocs (e.g. how to implement something like netlifly to build previews from pull requests)

[squidfunk]

I think that's pretty much what StackOverflow is for. Additionally there might be Slack or Discord channels for this topic.

[wilhelmer]

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.

We went live with RC4 yesterday! 🍾 https://docs.baslerweb.com

Good thing about launching on April 1st: If there are major bugs, you can always say haha first of April, was just a joke, we'll release the real version tomorrow ...

[rohancragg]

When trying out search tokenisation, I found I had to put the seaprator declaration in quotes
(per: https://deploy-preview-1486--mkdocs-material-preview.netlify.com/plugins/search/#tokenization )

like this

plugins:
  - search:
      separator: '[\s\-\.]+'

I got it working nicely here - thanks!: https://rohancragg.co.uk/

[squidfunk]

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

[rohancragg]

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

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

[squidfunk]

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.

[rohancragg]

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

[rohancragg]

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

You might want to add that to the upgrade steps.

[squidfunk]

pymdownx.superfences should continue to work.

[Andre601]

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.

[squidfunk]

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.

[facelessuser]

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

[rohancragg]

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

[facelessuser]

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.

[rohancragg]

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

[Andre601]

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)

[squidfunk]

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.

[Andre601]

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

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

[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 https://github.com/squidfunk/mkdocs-material/issues/1498#issuecomment-601020251

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