MkDocs Simple Hooks

0.1.5 · deprecated · verified Tue Apr 14

mkdocs-simple-hooks is a deprecated Python plugin for MkDocs that allowed users to define custom hooks directly within their project's Python modules without needing to create a separate MkDocs plugin package. Its functionality has been natively implemented in MkDocs 1.4 and later. The current version is 0.1.5, with the last release in January 2022, indicating an inactive release cadence.

Warnings

breaking This plugin is officially deprecated and no longer supported as MkDocs 1.4.0 and later versions include native support for hooks, making this plugin redundant. Users are strongly advised to migrate to the native MkDocs hooks functionality.
Fix: Remove `mkdocs-simple-hooks` from `mkdocs.yml` and `requirements.txt`. Refactor hook functions to be directly referenced under the `hooks:` configuration in `mkdocs.yml` as per MkDocs documentation.
gotcha If you don't have a `plugins` entry in your `mkdocs.yml`, MkDocs typically enables the `search` plugin by default. When you add `mkdocs-simple-hooks`, you must explicitly list `search` if you still want it, as adding any plugin disables implicit defaults.
Fix: Ensure your `mkdocs.yml` explicitly lists all desired plugins: `plugins: [search, mkdocs-simple-hooks]`
gotcha To enable/disable the plugin dynamically, especially in different environments, you can use MkDocs' `!ENV` tag with an environment variable. Without careful handling, the plugin might be active when not intended or vice-versa.
Fix: Configure in `mkdocs.yml`: `plugins: - mkdocs-simple-hooks: enabled: !ENV [ENABLE_MKDOCS_SIMPLE_HOOKS, True]` and set `ENABLE_MKDOCS_SIMPLE_HOOKS` accordingly in your environment.

Install

pip install mkdocs-simple-hooks Install latest version

Imports

Hook definition in mkdocs.yml
```
plugins:
  - mkdocs-simple-hooks:
      hooks:
        on_pre_build: "docs.hooks:copy_readme"
```
Hooks are defined as Python functions in a module (e.g., 'docs/hooks.py') and referenced as a string in mkdocs.yml, not directly imported into Python code.

Quickstart

To get started, define your hook functions in a Python file (e.g., `docs/hooks.py`) and then reference these functions in your `mkdocs.yml` configuration under the `plugins.mkdocs-simple-hooks.hooks` section. The example demonstrates copying `README.md` to `docs/index.md` before the build process.

# 1. Create a Python file, e.g., 'docs/hooks.py'
# content of docs/hooks.py:
import shutil

def copy_readme(*args, **kwargs):
    shutil.copy('README.md', 'docs/index.md')

# 2. Configure mkdocs.yml (add this to your existing mkdocs.yml):
# plugins:
#   - mkdocs-simple-hooks:
#       hooks:
#         on_pre_build: "docs.hooks:copy_readme"

# 3. Ensure 'mkdocs' is installed and run from your project root:
# pip install mkdocs
# mkdocs build
# mkdocs serve

view raw JSON →