Improve error message for missing Markdown extensions #782
Comments
Pymdown-extensions is not a required set of extensions as Mkdocs works great without them. Those extensions are just extras you can install if you like one or more of the extensions. I use them, but that is also because I wrote them :). |
Ah, because I use |
Yeah, that is really a Python Markdown thing. It is set to fail on extension import error. |
Yeah, okay - let's show a better error here if we can. Even if it just a nicer error that states something like this: "Your mkdocs.yml has a python-markdown extension that you don't seem to have installed locally" It is surprisingly difficult for us to tell users what package they need to install, because: Python packaging |
Right. You are wrapping a library, which raises an
My suggestion would be 1 or 3 above. There is no mechanism in place within MkDocs to handle an error raised during build. All the error handling is relegated to the config validation, which is why I mention options 2 and 3 (not to mention the potential for a "dirty" site dir in option 1). Option 3 sees like the best fix to me. |
Also because many times the user simply spelled it wrong, in which case nothing needs to be installed. However, it is nearly impossible to tell which it is and writing a "friendly" error message which covers both is tricky. |
A potential problem just occurred to me for both options 1 and 3 above. The error message provided by Markdown will need to be parsed to get the specific extension name which raised the error. You could just pass the message on, but that may not be "friendly". However, I don't recommend option 2 as the upcoming version 3 of the Markdown lib will be switching to using SetupTools entry points to load extensions by name. An option 2 solution will not work across Python-Markdown versions 2.x and 3.x. |
Neat! |
I have a working solution for option 3 above. If an extension $ mkdocs build
ERROR - Config value: 'markdown_extensions'. Error: Failed loading extension 'foo' from 'foo', 'markdown.extensions.foo' or 'mdx_foo'
Aborted with 1 Configuration Errors! The final part at the end of the message (after |
Fixes mkdocs#782. Note that we mock Markdown in the tests to ensure those tests are not using Markdown to validate the extension names. We don't mock Markdown in the tests which we do want Markdown to validate the extension names.
Fixes mkdocs#782. Note that we mock Markdown in the tests to ensure those tests are not using Markdown to validate the extension names. We don't mock Markdown in the tests which we do want Markdown to validate the extension names.
Fixes mkdocs#782. Note that we mock Markdown in the tests to ensure those tests are not using Markdown to validate the extension names. We don't mock Markdown in the tests which we do want Markdown to validate the extension names.
Fixes mkdocs#782. Note that we mock Markdown in the tests to ensure those tests are not using Markdown to validate the extension names. We don't mock Markdown in the tests which we do want Markdown to validate the extension names. Also ensure project-min has all relevant extensions.
Fixes #782. Note that we mock Markdown in the tests to ensure those tests are not using Markdown to validate the extension names. We don't mock Markdown in the tests which we do want Markdown to validate the extension names. Also ensure project-min has all relevant extensions.
I keep getting this but no idea how to resolve it, am i missing something? |
@samoclay according to the error, |
@waylan i have now removed the lightgallery from my mkdocs.yml and tried to rebuild the docs.
I have a feeling might be something to do with how my mac uses python |
@samoclay I suspect you are correct. If you run the command Something you can do to check that is to run I see that your files appear to be under a |
I just had to install that manually.
The text was updated successfully, but these errors were encountered: