Closed squidfunk closed 4 years ago
@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:
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 intype
.claim
will callev.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.
... and implemented here:
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:
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:
role=...
?)@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:
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...
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 pip
s 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.
@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
Help test Material 5 RC 4! Deploy preview
Please post any problems you encounter during migration in this issue.
Installation
Using
pip
:Using
docker
:Features
__material.dialog$.next("Hi!")
in the console!Fixed in RC 2
pymdownx.inline
andinline
Fixed in RC 3
Fixed in RC 4
popstate
event triggeredhistory.pushState
againrequired
attribute on search inputMigration
See the migration guide in the deploy preview.