User needs to set `PYTHONPATH` to build

[alexvoss]

The custom slugify extensions that the tutorial demonstrates requires that the PYTHONPATH variable is set so that . is on it. This is currently not described and, in any case, a bit annoying because there is always the potential that people forget to do this and, even worse, have to solve the problem over and over again if they do not often write Python code.

Another approach might be to merge hooks/ into ext/ and use the fact that MkDocs puts the directory containing the hooks on the PYTHONPATH. There is no guarantee, however, that it will continue to do this.

Which solution is worse? Thoughts, @squidfunk?

This came up in the discussion of https://github.com/mkdocs-material/create-blog/issues/1.

[squidfunk]

We might raise a feature request to the maintainers of MkDocs to add the directory in which mkdocs.yml resides to PYTHONPATH for easier and consistent resolution of custom functions referenced via YAML tags. However, requests to discuss the public API, especially the extension API of MkDocs, have stalled in the past. Latest attempts:

• https://github.com/mkdocs/mkdocs/issues/3644
• https://github.com/mkdocs/mkdocs/issues/3331

Thus, as hooks is automatically included, we can just recommend to use it (for now).

[alexvoss]

Thus, as hooks is automatically included, we can just recommend to use it (for now).

Ok, I will create a PR on that basis for the tutorial and change the template accordingly as well.

[squidfunk]

An issue was created with a similar problem: https://github.com/mkdocs/mkdocs/issues/3772

[alexvoss]

Just stumbled across the fact that the MkDocs documentation actually documents what I found (under New in MkDocs 1.6). The contents of the directory that a hook is in gets added to the sys.path so a hook can import foo if there is a file foo.py in the same folder. So, at least adding a hook is a workaround that does not rely on undocumented behavior. Until there is an official way, I will use this in my projects and call the directory ext instead of hooks, because I will now throw all kinds of Python code into that.

As to the tutorial, I am not so sure.

[squidfunk]

Jup, @pawamoy already noted this upstream in https://github.com/mkdocs/mkdocs/issues/3772#issuecomment-2239234025.

[mschoettle]

I just stumbled across this trying to run mkdocs serve from this repo. Running it via PYTHONPATH=. mkdocs serve seems to work.

[squidfunk]

Jup. Unfortunately no progress on the issue in the last months.