Skip to content

Installation

Assuming you're inside your mkdocs project directory...

1. Install macros

Install macros via mkdocs-macros-plugin as well as required packages

pip install mkdocs-macro-plugin mrkdwn_analysis pathspec python-frontmatter

And include it in your mkdocs.yml file:

plugins:
  - search
  - macros

2. Create an mkdocs hook

Add an mkdocs hook e.g. hooks.py in your project's root directory (not the docs directory) with the following content:

hooks.py
def on_nav(nav, config, files):
    # overrides config.nav for macros use
    config.nav = nav
    return nav

This is important for use in lsnav(), as it allows the macro to receive nav events from mkdocs/other plugins.

3. Create main.py:

Copy the contents of main.py into the project directory.

With wget:

wget https://raw.githubusercontent.com/skedastically/mkdocs-macros-gimmicks/refs/heads/main/main.py

Now you can start using commands such as {{ lsdir() }} and see their results during mkdocs serve

Further resources