tessl/pypi-mkdocs-macros-plugin

Unleash the power of MkDocs with macros and variables

—

Pending

Overview

Eval results

Files

Built-in Functions

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

Default macros and filters provided by the plugin for common templating tasks, documentation generation, and utility functions.

Capabilities

Documentation Macros

Built-in macros for generating documentation and debugging template environments.

def context(obj: dict = None) -> list:
    """
    List variables and their types/values for documentation.
    
    Args:
        obj: Object to inspect (defaults to all template variables)
        
    Returns:
        List of (name, type, formatted_value) tuples
    """

def macros_info() -> str:
    """
    Generate comprehensive documentation of the plugin environment.
    
    Returns:
        HTML documentation showing all variables, macros, and filters
    """

Usage Examples

Variable inspection:

## Available Variables

{{ context() | pretty }}

## Page Variables Only

{{ context(page) | pretty }}

## Configuration Variables

{{ context(config) | pretty }}

Complete environment documentation:

{{ macros_info() }}

Custom object inspection:

{% set my_data = {'name': 'John', 'age': 30} %}

{{ context(my_data) | pretty }}

Time and Date Macros

Built-in macros for working with dates and timestamps.

def now() -> datetime:
    """
    Get current datetime at build time.
    
    Returns:
        datetime object representing build time
    """

Usage Examples

Current timestamp:

Built on {{ now() }}

Copyright {{ now().year }} My Company

Formatted dates:

Last updated: {{ now().strftime('%Y-%m-%d %H:%M:%S') }}

Today is {{ now().strftime('%A, %B %d, %Y') }}

Date arithmetic:

{% set build_date = now() %}
{% set days_in_year = 365 %}

This documentation was built on day {{ build_date.timetuple().tm_yday }} of {{ build_date.year }}.

URL Utilities

Built-in macros for handling URLs and relative links.

def fix_url(url: str) -> str:
    """
    Convert relative URLs to point to docs directory.
    
    Args:
        url: URL to fix (relative or absolute)
        
    Returns:
        Fixed URL that points to correct location
    """

Usage Examples

Image links:

![Logo]({{ fix_url('images/logo.png') }})

[Download]({{ fix_url('assets/manual.pdf') }})

Dynamic URLs:

{% set image_path = 'screenshots/' + page.title.lower() + '.png' %}
![Screenshot]({{ fix_url(image_path) }})

Documentation Filters

Built-in filters for formatting and presenting template data.

def pretty(var_list: list) -> str:
    """
    Format output from context() macro as HTML table.
    
    Args:
        var_list: List of (name, type, content) tuples from context()
        
    Returns:
        HTML table with formatted variable information
    """

Usage Examples

Variable documentation:

## Template Variables

{{ context() | pretty }}

## Git Information

{{ context(git) | pretty }}

Custom object formatting:

{% set project_info = {
    'name': config.site_name,
    'version': version,
    'author': author
} %}

{{ context(project_info) | pretty }}

URL Filters

Built-in filters for URL manipulation and path handling.

def relative_url(path: str) -> str:
    """
    Convert path to URL relative to current page.
    
    Args:
        path: Page path to convert
        
    Returns:
        URL relative to current page
    """

Usage Examples

Navigation links:

[Home]({{ 'index.md' | relative_url }})

[API Reference]({{ 'api/index.md' | relative_url }})

Dynamic navigation:

{% for nav_page in navigation.pages %}
- [{{ nav_page.title }}]({{ nav_page.url | relative_url }})
{% endfor %}

Cross-references:

See also: [{{ page.title }}]({{ page.url | relative_url }})

Combined Usage Patterns

Dynamic Documentation Generation

# {{ config.site_name }} Documentation

Generated on {{ now().strftime('%Y-%m-%d') }} from commit {{ git.short_commit }}.

## Project Information

{{ context({
    'Site': config.site_name,
    'Version': version,
    'Python': environment.python_version,
    'MkDocs': environment.mkdocs_version
}) | pretty }}

## Available Macros

{{ context(macros) | pretty }}

Environment-Specific Content

{% set env_info = {
    'Build System': environment.system,
    'Build Time': now(),
    'Git Branch': git.tag or 'main',
    'Debug Mode': plugin.verbose
} %}

## Build Information

{{ context(env_info) | pretty }}

{% if plugin.verbose %}
## Debug Information

{{ macros_info() }}
{% endif %}

Asset Management

{% set assets = {
    'logo': fix_url('images/logo.svg'),
    'stylesheet': fix_url('css/custom.css'),
    'script': fix_url('js/app.js')
} %}

<link rel="stylesheet" href="{{ assets.stylesheet }}">
<script src="{{ assets.script }}"></script>

![Company Logo]({{ assets.logo }})

Navigation Generation

## Quick Navigation

{% for section in navigation.items %}
{% if section.is_section %}
### {{ section.title }}
{% for page in section.children %}
- [{{ page.title }}]({{ page.url | relative_url }})
{% endfor %}
{% endif %}
{% endfor %}

---
*Generated {{ now().strftime('%B %d, %Y') }}*

Error Handling

Built-in functions include error handling for common issues:

<!-- Safe git access -->
{% if git.status %}
Last commit: {{ git.short_commit }}
{% else %}
Not a git repository
{% endif %}

<!-- Safe URL handling -->
{{ fix_url('path/that/might/not/exist.png') }}

<!-- Safe context inspection -->
{{ context(undefined_variable) | pretty }}

Function Availability

All built-in functions are automatically available in templates without imports:

Available in all markdown files
Available in included templates
Available in macro definitions
Can be overridden by custom functions with same names

Performance Considerations

now() returns the same datetime object throughout the build
context() and macros_info() generate HTML on each call
fix_url() performs path manipulation on each call
Use {% set %} to cache results of expensive operations:

{% set build_time = now() %}
{% set project_vars = context() %}

Built: {{ build_time }}
Variables: {{ project_vars | pretty }}

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