Closed ghost closed 3 years ago
Looking at the MkDocs docs, the short answer is "no". If you want to use mike
, you'll have to avoid INHERIT
for now. However, with some fixes, it should be possible to (mostly?) get mike
working with INHERIT
.
I'm a little skeptical about the INHERIT
feature though, since the documentation doesn't bother to explain how plugins
get merged across multiple configurations. Specifically, the docs are silent on the order of plugins after merging. Since dicts in Python 3.6+ are ordered, the behavior is predictable at least, but it does matter whether the child config's plugins are put before or after the parent config's: plugins can modify the MkDocs configuration, so running plugins in a different order can result in different output. Because this isn't mentioned in the docs, I can only assume that the order (whatever it is) is unspecified and could change at any time in a point release.
Good and clear answer, thank you.
I hadn't considered the consequences, only the inflexibility, such was my desperation to try anything to tame multiple nav
elements across several files. It's better than nothing but only if using mkdocs
directly.
I'm going to reopen this to track the fix for mike
so that it works (as best as it can, at least) with INHERIT
. It should be relatively straightforward to handle this for docs that don't depend on plugin ordering. If plugin ordering does cause issues in some cases, that's probably an MkDocs bug, and I'll let them handle it; that issue isn't specific to mike
, and would be likely to crop up elsewhere too.
fyi - I've managed to get some success for both inherit and for !ENV by leveraging mkdocs.utils.yaml_load instead of yaml.load in mkdocs_utils.py within a fork. These two lines (plus one for the import) are the only things I needed to change, but it's entirely possible I've just not hit a use case that doesn't work for yet.
@chris-twiner Looking at the implementation of mkdocs.utils.yaml_load
, that seems like a reasonable solution, and I can't think of a situation where it won't work. There might be a still-better way (I'll look into this when I get the chance), but you shouldn't run into any issues with that change.
Ok, INHERIT
and !ENV
should work now, as well as specifying plugins
as a dict. This will go out in v1.1.0, which I'll probably release in a few weeks if nothing major comes up.
Very cool, many thanks!
This will go out in v1.1.0, which I'll probably release in a few weeks if nothing major comes up.
Any ETA for 1.1.0?
Probably this week, since the only remaining thing I want to add is some documentation about working with CI (that's a pretty common issue that gets filed).
Ok, I've just published v1.1.0, so now this should be available to everyone via PyPI.
It's excellent and pushed to production! Thanks.
Is mike 1.0.1 compatible with mkdocs 1.2
INHERIT
token?I'm rejigging a set of configs to use the
INHERIT
feature but when running mike I geterror: 'dict' object has no attribute 'insert'
.