Skip to main content

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

Project description

mkdocs-simple-hooks

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

Setup

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:

plugins:
  - search
  - mkdocs-simple-hooks:
      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.

Usage

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.

Example

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

import shutil

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

Now, register the hook in your mkdocs.yml:

plugins:
  - mkdocs-simple-hooks:
      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:

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

Which enables you to disable the plugin locally using:

export ENABLE_MKDOCS_SIMPLE_HOOKS=false
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 details)

Uploaded Source

Built Distribution

mkdocs_simple_hooks-0.1.5-py3-none-any.whl (4.6 kB view details)

Uploaded Python 3

File details

Details for the file mkdocs-simple-hooks-0.1.5.tar.gz.

File metadata

  • Download URL: mkdocs-simple-hooks-0.1.5.tar.gz
  • Upload date:
  • Size: 4.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.7.1 importlib_metadata/4.8.3 pkginfo/1.8.2 requests/2.27.1 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.6.4

File hashes

Hashes for mkdocs-simple-hooks-0.1.5.tar.gz
Algorithm Hash digest
SHA256 dddbdf151a18723c9302a133e5cf79538be8eb9d274e8e07d2ac3ac34890837c
MD5 9e59972f905fed8419c4f6446ba45231
BLAKE2b-256 f193565f98d6810e3b493e61160aea1cceb8653331576e7fa7f048ac7e7cdf62

See more details on using hashes here.

File details

Details for the file mkdocs_simple_hooks-0.1.5-py3-none-any.whl.

File metadata

  • Download URL: mkdocs_simple_hooks-0.1.5-py3-none-any.whl
  • Upload date:
  • Size: 4.6 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.7.1 importlib_metadata/4.8.3 pkginfo/1.8.2 requests/2.27.1 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.6.4

File hashes

Hashes for mkdocs_simple_hooks-0.1.5-py3-none-any.whl
Algorithm Hash digest
SHA256 efeabdbb98b0850a909adee285f3404535117159d5cb3a34f541d6eaa644d50a
MD5 683fc9bb094512d9a360969e947c4981
BLAKE2b-256 7ae97bf0f928f5b6cdd602d4a01d52e5fc1eba8d3ba6d97619a88fc271a625f8

See more details on using hashes here.

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