Hooks feature: run plugin events from local Python files

[oprypin]

Add a new hooks config to mkdocs.yml:

A list of paths to Python scripts (relative to mkdocs.yml) that are loaded and used as plugin instances.

For example:

hooks:
    - my_hooks.py

Then the file my_hooks.py can contain any plugin event handlers (without self), e.g.:

def on_page_markdown(markdown, **kwargs):
    return markdown.replace('a', 'z')

This does not enable any new abilities compared to plugins, it only simplifies one-off usages, as these don't need to be installed like plugins do.

Note that for mkdocs serve the hook module will not be reloaded on each build.

You might have seen this feature in the mkdocs-simple-hooks plugin by @aklajnert. If using standard method names, it can be directly replaced, e.g.:

-plugins:
-  - mkdocs-simple-hooks:
-      hooks:
-        on_page_markdown: 'my_hooks:on_page_markdown'
+hooks:
+  - my_hooks.py

[ultrabug]

You might have seen this feature in the mkdocs-simple-hooks plugin by @aklajnert. If using standard method names, it can be directly replaced, e.g.:

Maybe as a courtesy for @aklajnert you could share your rationale in implementing this straight in MkDocs (other than not having to install something)?

Some users may argue that we often push back such ideas to the responsibility of plugins, so I'd like it to be clear here.

Thanks

[oprypin]

Sure, you have a point there.

I think it's been too many times that I wanted to suggest a solution to someone in Discussions which was just to throw a few lines of code into a file, at which point installing that plugin constituted more than half of the remaining complexity.

And this plays better with (mainly new) MkDocs features: priorities also work, persisting state within mkdocs serve works, paths are handled correctly with mkdocs build -f foo/mkdocs.yml.

And pushing back to plugins is something that I want to reduce, particularly when a feature is unlikely to invite "configuration creep", that is, when people would each start to request a tiny tweak to the configuration for their use case.
Here I expect to require no configuration.

[aklajnert]

FYI, initially I asked to put it into the core (see #2091), but I decided it will be faster, and easier to implement as a plugin.

[ultrabug]

Sure, you have a point there.

And you have a point too, thanks for clarifying that for everyone.

[sreenivasulureddysura]

@oprypin this feature is not working mkdoc verison 1.4.2

[ultrabug]

@sreenivasulureddysura please fill a complete bug report with a clear procedure to reproduce the problem you are facing.

Dropping a comment on a closed PR is not helpful I'm afraid.

Thanks