Skip to main content

Define your own hooks for mkdocs, without having to create a new package.

Project description


Define your own hooks for mkdocs, without having to create a new package.


Install the plugin using pip:

pip install mkdocs-simple-hooks

Next, add a python module to either the docs/ directory or the root mkdocs directory. Then, add the plugin and hooks definition to your mkdocs.yml:

  - search
  - mkdocs-simple-hooks:
        hook-name: "your.module:hook_function"

If you have no plugins entry in your config file yet, you'll likely also want to add the search plugin. MkDocs enables it by default if there is no plugins entry set.

More information about plugins in the MkDocs documentation.


You can use this plugin to create simple hooks for mkdocs without having to create a separate plugin package.

Just define a function and register it as a hook in the mkdocs.yml. The function shall have the same API as the desired hook. To see available hooks and their API, see the events chapter in the mkdocs documentation.


Let's say you want to copy the file to docs/ To do that, create a new file, e.g.: docs/, and put the following function there:

import shutil

def copy_readme(*args, **kwargs):
    shutil.copy("", "docs/")

Now, register the hook in your mkdocs.yml:

  - mkdocs-simple-hooks:
        on_pre_build: "docs.hooks:copy_readme"

That's all - the copy_readme() function will run every time, before building the documentation.

Disabling the plugin

You can use the enabled option to optionally disable this plugin. A possible use case is local development where you might want faster build times. It's recommended to use this option with an environment variable together with a default fallback (introduced in mkdocs v1.2.1, see docs). Example:

  - mkdocs-simple-hooks:
      enabled: !ENV [ENABLE_MKDOCS_SIMPLE_HOOKS, True]
        on_pre_build: "docs.hooks:copy_readme"

Which enables you to disable the plugin locally using:

mkdocs serve

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mkdocs-simple-hooks-0.1.5.tar.gz (4.0 kB view hashes)

Uploaded source

Built Distribution

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page