tessl/pypi-mkdocs-macros-plugin

Unleash the power of MkDocs with macros and variables

—

Pending

Overview

Eval results

Files

Plugin Configuration

Name: tessl/pypi-mkdocs-macros-plugin
Author: tessl

Configuration options for controlling plugin behavior, template rendering, Jinja2 settings, and module loading. These settings are defined in the mkdocs.yml file under the macros plugin section.

Capabilities

Basic Configuration

Core configuration options for module loading and rendering behavior.

# In mkdocs.yml under plugins: - macros:
module_name: str = 'main'          # Python module filename for macros
modules: list = []                 # List of pre-installed modules (pluglets)  
render_by_default: bool = True     # Render pages by default vs opt-in
verbose: bool = False              # Enable verbose logging

Usage Examples

Basic configuration:

plugins:
  - macros:
      module_name: custom_macros
      verbose: true

With multiple pluglets:

plugins:
  - macros:
      modules:
        - mkdocs-macros-test
        - custom-pluglet:my_module
      render_by_default: false

Path and File Configuration

Options for controlling which files are rendered and where template includes are located.

force_render_paths: str = ''       # Pathspec patterns to force rendering
include_dir: str = ''              # Directory for {% include %} and {% import %} files
include_yaml: list = []            # Additional YAML files to load

Usage Examples

Force rendering specific paths:

plugins:
  - macros:
      force_render_paths: |
        docs/generated/**
        api/*.md
        !docs/static/**

Include configuration:

plugins:
  - macros:
      include_dir: templates
      include_yaml:
        - data/constants.yml
        - config/variables.yml
        - nested_key: data/nested.yml

Jinja2 Template Configuration

Custom Jinja2 template markers for avoiding conflicts with other systems.

j2_block_start_string: str = ''    # Custom Jinja2 block start marker (default: {%)
j2_block_end_string: str = ''      # Custom Jinja2 block end marker (default: %})
j2_variable_start_string: str = '' # Custom Jinja2 variable start marker (default: {{)
j2_variable_end_string: str = ''   # Custom Jinja2 variable end marker (default: }})
j2_comment_start_string: str = ''  # Custom Jinja2 comment start marker (default: {#)
j2_comment_end_string: str = ''    # Custom Jinja2 comment end marker (default: #})

Usage Examples

Custom markers to avoid conflicts:

plugins:
  - macros:
      j2_variable_start_string: '<<'
      j2_variable_end_string: '>>'
      j2_block_start_string: '<<%'
      j2_block_end_string: '%>>'

With custom markers, use:

Project name: << config.site_name >>

<<% if environment.system == 'Darwin' %>>
Running on macOS
<<% endif %>>

Error Handling Configuration

Options for controlling behavior when template rendering encounters errors or undefined variables.

on_undefined: str = 'keep'         # Behavior for undefined variables: 'keep', 'silent', 'strict', 'lax'
on_error_fail: bool = False        # Exit on rendering errors in CI/CD

Undefined Variable Behaviors

'keep' (default): Leave undefined variables as-is in output
'silent': Replace undefined variables with empty string
'strict': Raise exception on undefined variables
'lax': Pass any unknown objects as empty string

Usage Examples

Strict mode for development:

plugins:
  - macros:
      on_undefined: strict
      on_error_fail: true

Production-safe configuration:

plugins:
  - macros:
      on_undefined: silent
      on_error_fail: false

Complete Configuration Example

plugins:
  - macros:
      # Module configuration
      module_name: project_macros
      modules:
        - mkdocs-macros-test
        - company-pluglet:shared_macros
      
      # Rendering configuration
      render_by_default: true
      force_render_paths: |
        docs/api/**
        docs/generated/*.md
        !docs/static/**
      
      # Template includes
      include_dir: templates
      include_yaml:
        - data/project_vars.yml
        - constants: config/constants.yml
      
      # Custom Jinja2 markers (if needed)
      j2_variable_start_string: '[['
      j2_variable_end_string: ']]'
      
      # Error handling
      on_undefined: keep
      on_error_fail: false
      verbose: true

Page-Level Control

Individual pages can override rendering behavior using YAML front matter:

---
render_macros: true   # Force rendering even if render_by_default is false
render_macros: false  # Skip rendering even if render_by_default is true
---

# Page content here

Install with Tessl CLI

npx tessl i tessl/pypi-mkdocs-macros-plugin

docs

built-in-context.md

built-in-functions.md

external-integration.md

index.md

module-system.md

plugin-configuration.md

template-environment.md

tile.json

tessl/pypi-mkdocs-macros-plugin