Using a local extension with Python-Markdwon

[jdumas]

Right now it seems that the only way to use an extension for Python-Markdown with mkdocs is to have it installed somewhere in the python path (usually via pip), and have it recognized as a standard python module.

I would like to be able to use an extension that has no pip package, or write my own without requiring every user to install something on their system.

Would it be possible to add a yaml option to specify a list of local extensions to pass to Python-Markdown? (Either messing with the PYTHONPATH, sys.path.append, or loading the file directly with importlib and passing the user-defined object to markdown.markdown).

[facelessuser]

You can run local extensions if you use python -m mkdocs as the cwd is loaded up in the path, so modules will be sourced from locally first. I'm not sure if this will always be the case with Python, but currently it has been.

[jdumas]

Hmm nice it works. I didn't know you could do that. Still a bit inconvenient having to type python -m mkdocs serve rather than mkdocs serve, but I'll take it for now.

[waylan]

As Markdown's extension loading is handled by the Markdown lib, this is an upstream issue. MkDocs just blindly passes the strings on to Markdown and I don't see any reason to change that. Therefore, this would be something you would need to address with the Markdown library. However, Python-Markdown is in the process of changing this in the next major release in the opposite direction, so its not likely your request would get must traction.

[jdumas]

I don't see how this PR of yours changes anything when passing a local module to Python-Markdown. Note that on the MkDocs side, you could also offer the possibility to load custom user instances for local extensions, and pass those to Python-Markdown. It's not strictly necessary, as calling MkDocs via python -m mkdocs serve allows to workaround that, but it makes calling mkdocs less direct, and the writing of extensions more annoying.

[waylan]

MkDocs does not pass "modules" to Python-Markdown. We pass a "string" to Python-Markdown. That string must be in a format which Python-Markdown will understand. To do anything more than that, we would need to re-implement Markdown's extension loading mechanism.

For example, if a use provides a string in the mkdocs.yml config file, how do we determine if that string points to a module on the PYHTONPATH or not? And if its not, then what? Mucking with PYTHONPATH, sys.path.append, etc consistently across all supported systems sound like a maintenance headache I don't want. As was already pointed out, Python automatically includes the CWD in the path and that seems good enough to me.

[jdumas]

All I'm saying is, you could use a different yaml option for local extensions. Or have the possibility for a MkDocs plugin to register it own extra Python-Markdown plugins, etc. It looks like MkDocs plugins also need to be in the python path which is a bit annoying. Again this is mostly a theoretical issue, as we've determined there's a way around that already, but it doesn't have to be horribly complicated either.

[waylan]

this is mostly a theoretical issue,

Well, in my opinion, not having things on the python path is generally a bad idea and not something I want to support ever anywhere.

I pointed to the upcoming changes to Markdown because those changes include using entry points to point at Markdown extensions. Entry points require the extensions to be "installed" just like MkDocs uses entry points for plugins; requiring them to be installed. IMO, this is a good thing.

To be clear, having every dependency for every thing I every played with available system wide is not a good thing. But that's why we have virtualenv. Just install those dependencies in a virtual environment and activate that environment when you want to build your MkDocs site. That's what I do and what I recommend others do as well.

And, of course, there is the issue of being able to import the code you are currently working on. But that is resolved with Setuptools' develop mode (and pip's --editable option). In the end, there are no reasons to not install a package.

[jdumas]

I mean you're probably right, but then you need to know how to use virtualenv, write the setuptool for your local extension, have every user install it locally when they want to compile the website, etc. It is certainly possible, but very much less "out of the box" experience than just running pip install mkdocs and then mkdocs serve on your repository.