feat(Dependencies): Update dependency mkdocs to v1.6.0 #324
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR contains the following updates:
==1.5.3
->==1.6.0
Release Notes
mkdocs/mkdocs (mkdocs)
v1.6.0
Compare Source
Local preview
mkdocs serve
no longer locks up the browser when more than 5 tabs are open. This is achieved by closing the polling connection whenever a tab becomes inactive. Background tabs will no longer auto-reload either - that will instead happen as soon the tab is opened again. Context: #3391New flag
serve --open
to open the site in a browser.After the first build is finished, this flag will cause the default OS Web browser to be opened at the home page of the local site.
Context: #3500
Drafts
The
exclude_docs
config was split up into two separate concepts.The
exclude_docs
config no longer has any special behavior formkdocs serve
- it now always completely excludes the listed documents from the site.If you wish to use the "drafts" functionality like the
exclude_docs
key used to do in MkDocs 1.5, please switch to the new config keydraft_docs
.See documentation.
Other changes:
Update to deduction of page titles
MkDocs 1.5 had a change in behavior in deducing the page titles from the first heading. Unfortunately this could cause unescaped HTML tags or entities to appear in edge cases.
Now tags are always fully sanitized from the title. Though it still remains the case that
Page.title
is expected to contain HTML entities and is passed directly to the themes.Images (notably, emojis in some extensions) get preserved in the title only through their
alt
attribute's value.Context: #3564, #3578
Themes
"readthedocs" theme
Fix: "readthedocs" theme can now correctly handle deeply nested nav configurations (over 2 levels deep), without confusedly expanding all sections and jumping around vertically. (#3464)
Fix: "readthedocs" theme now shows a link to the repository (with a generic logo) even when isn't one of the 3 known hosters. (#3435)
"readthedocs" theme now also has translation for the word "theme" in the footer that mistakenly always remained in English. (#3613, #3625)
"mkdocs" theme
The "mkdocs" theme got a big update to a newer version of Bootstrap, meaning a slight overhaul of styles. Colors (most notably of admonitions) have much better contrast.
The "mkdocs" theme now has support for dark mode - both automatic (based on the OS/browser setting) and with a manual toggle. Both of these options are not enabled by default and need to be configured explicitly.
See
color_mode
,user_color_mode_toggle
in documentation.Context: #3493, #3649
Configuration
New "
enabled
" setting for all pluginsYou may have seen some plugins take up the convention of having a setting
enabled: false
(or usually controlled through an environment variable) to make the plugin do nothing.Now every plugin has this setting. Plugins can still choose to implement this config themselves and decide how it behaves (and unless they drop older versions of MkDocs, they still should for now), but now there's always a fallback for every plugin.
See documentation. Context: #3395
Validation
Validation of hyperlinks between pages
Absolute links
If you dislike having to always use relative links, now you can opt into absolute links and have them work correctly.
If you set the setting
validation.links.absolute_links
to the new valuerelative_to_docs
, all Markdown links starting with/
will be understood as being relative to thedocs_dir
root. The links will then be validated for correctness according to all the other rules that were already working for relative links in prior versions of MkDocs. For the HTML output, these links will still be turned relative so that the site still works reliably.So, now any document (e.g. "dir1/foo.md") can link to the document "dir2/bar.md" as
[link](/dir2/bar.md)
, in addition to the previously only correct way[link](../dir2/bar.md)
.You have to enable the setting, though. The default is still to just skip any processing of such links.
See documentation. Context: #3485
Absolute links within nav
Absolute links within the
nav:
config were also always skipped. It is now possible to also validate them in the same way withvalidation.nav.absolute_links
. Though it makes a bit less sense because then the syntax is simply redundant with the syntax that comes without the leading slash.Anchors
There is a new config setting that is recommended to enable warnings for:
Example of a warning that this can produce:
Any of the below methods of declaring an anchor will be detected by MkDocs:
Plugins and extensions that insert anchors, in order to be compatible with this, need to be developed as treeprocessors that insert
etree
elements as their mode of operation, rather than raw HTML which is undetectable for this purpose.If you as a user are dealing with falsely reported missing anchors and there's no way to resolve this, you can choose to disable these messages by setting this option to
ignore
(and they are at INFO level by default anyway).See documentation. Context: #3463
Other changes:
When the
nav
config is not specified at all, thenot_in_nav
setting (originally added in 1.5.0) gains an additional behavior: documents covered bynot_in_nav
will not be part of the automatically deduced navigation. Context: #3443Fix: the
!relative
YAML tag formarkdown_extensions
(originally added in 1.5.0) - it was broken in many typical use cases.See documentation. Context: #3466
Config validation now exits on first error, to avoid showing bizarre secondary errors. Context: #3437
MkDocs used to shorten error messages for unexpected errors such as "file not found", but that is no longer the case, the full error message and stack trace will be possible to see (unless the error has a proper handler, of course). Context: #3445
Upgrades for plugin developers
Plugins can add multiple handlers for the same event type, at multiple priorities
See
mkdocs.plugins.CombinedEvent
in documentation. Context: #3448Enabling true generated files and expanding the
File
APISee documentation.
There is a new pair of attributes
File.content_string
that becomes the official API for obtaining the content of a file and is used by MkDocs itself.This replaces the old approach where one had to manually read the file located at
File.abs_src_path
, although that is still the primary action that these new attributes do under the hood.The content of a
File
can be backed by a string and no longer has to be a real existing file atabs_src_path
.It is possible to set the attribute
File.content_string
orFile.content_bytes
and it will take precedence overabs_src_path
.Further,
abs_src_path
is no longer guaranteed to be present and can beNone
instead. MkDocs itself still uses physical files in all cases, but eventually plugins will appear that don't populate this attribute.There is a new constructor
File.generated()
that should be used by plugins instead of theFile()
constructor. It is much more convenient because one doesn't need to manually look up the values such asdocs_dir
anduse_directory_urls
. Its signature is one of:This way, it is now extremely easy to add a virtual file even from a hook:
For large content it is still best to use physical files, but one no longer needs to manipulate the path by providing a fake unused
docs_dir
.There is a new attribute
File.generated_by
that arose by convention - for generated files it should be set to the name of the plugin (the key in theplugins:
collection) that produced this file. This attribute is populated automatically when using theFile.generated()
constructor.It is possible to set the
edit_uri
attribute of aFile
, for example from a plugin or hook, to make it different from the default (equal tosrc_uri
), and this will be reflected in the edit link of the document. This can be useful because some pages aren't backed by a real file and are instead created dynamically from some other source file or script. So a hook could set theedit_uri
to that source file or script accordingly.The
File
object now stores its originalsrc_dir
,dest_dir
,use_directory_urls
values as attributes.Fields of
File
are computed on demand but cached. Only the three above attributes are primary ones, and partly alsodest_uri
. This way, it is possible to, for example, overwritedest_uri
of aFile
, andabs_dest_path
will be calculated based on it. However you need to clear the attribute first usingdel f.abs_dest_path
, because the values are cached.File
instances are now hashable (can be used as keys of adict
). Two files can no longer be considered "equal" unless it's the exact same instance ofFile
.Other changes:
The internal storage of
File
objects inside aFiles
object has been reworked, so any plugins that choose to accessFiles._files
will get a deprecation warning.The order of
File
objects inside aFiles
collection is no longer significant when automatically inferring thenav
. They get forcibly sorted according to the default alphabetic order.Context: #3451, #3463
Hooks and debugging
Hook files can now import adjacent *.py files using the
import
statement. Previously this was possible to achieve only through asys.path
workaround. See the new mention in documentation. Context: #3568Verbose
-v
log shows the sequence of plugin events in more detail - shows each invoked plugin one by one, not only the event type. Context: #3444Deprecations
Python 3.7 is no longer supported, Python 3.12 is officially supported. Context: #3429
The theme config file
mkdocs_theme.yml
no longer executes YAML tags. Context: #3465The plugin event
on_page_read_source
is soft-deprecated because there is always a better alternative to it (see the newFile
API or juston_page_markdown
, depending on the desired interaction).When multiple plugins/hooks apply this event handler, they trample over each other, so now there is a warning in that case.
See documentation. Context: #3503
API deprecations
It is no longer allowed to set
File.page
to a type other thanPage
or a subclass thereof. Context: #3443 - following the deprecation in version 1.5.3 and #3381.Theme._vars
is deprecated - usetheme['foo']
instead oftheme._vars['foo']
utils
:modified_time()
,get_html_path()
,get_url_path()
,is_html_file()
,is_template_file()
are removed.path_to_url()
is deprecated.LiveReloadServer.watch()
no longer accepts a custom callback.Context: #3429
Misc
sitemap.xml.gz
file is slightly more reproducible and no longer changes on every build, but instead only once per day (upon a date change). Context: #3460Other small improvements; see commit log.
Configuration
📅 Schedule: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined).
🚦 Automerge: Disabled by config. Please merge this manually once you are satisfied.
♻ Rebasing: Whenever PR is behind base branch, or you tick the rebase/retry checkbox.
🔕 Ignore: Close this PR and you won't be reminded about this update again.
This PR has been generated by Mend Renovate. View repository job log here.