tessl/pypi-mkdocs-material

Material Design theme for MkDocs with built-in plugins for blogs, search, social cards, and privacy compliance

—

Pending

Overview

Eval results

Files

Additional Plugins

Name: tessl/pypi-mkdocs-material
Author: tessl

Specialized plugins providing metadata management, plugin grouping, offline support, and environment information gathering. These utility plugins extend MkDocs Material's functionality for specific use cases and development workflows.

Capabilities

Meta Plugin

Metadata management plugin for processing and injecting metadata across documentation pages.

plugins:
  - material/meta:
      enabled: true              # Enable meta plugin (default: true)
      meta_file: "**/.meta.yml"  # Metadata file pattern

Meta Plugin Configuration

plugins:
  - material/meta:
      meta_file: "**/.meta.yml"        # Metadata file pattern
      meta_file_recursive: true        # Recursive metadata inheritance
      meta_file_inherit: true          # Inherit parent metadata

Metadata File Structure

# .meta.yml
title: Section Title
description: Section description
authors:
  - John Doe
  - Jane Smith
tags:
  - documentation
  - api
template: custom.html

Group Plugin

Plugin grouping and organization functionality for managing complex plugin configurations.

plugins:
  - material/group:
      enabled: true              # Enable group plugin (default: true)
      plugins: []               # Plugin group configuration

Group Plugin Configuration

plugins:
  - material/group:
      plugins:
        - group: development
          plugins:
            - material/info
            - material/meta
        - group: production
          plugins:
            - material/privacy
            - material/social

Offline Plugin

Offline support functionality for creating documentation that works without internet connectivity.

plugins:
  - material/offline:
      enabled: true              # Enable offline support (default: true)

Offline Plugin Features

Service worker generation
Asset caching strategies
Offline-first navigation
Progressive web app capabilities

Info Plugin

Environment and build information gathering for debugging and development workflows.

plugins:
  - material/info:
      enabled: true                    # Enable info plugin (default: true)
      archive: true                   # Create info archive (default: true)
      archive_stop_on_violation: true  # Stop on policy violations

Info Plugin Configuration

plugins:
  - material/info:
      archive: true                   # Generate info archive
      archive_format: zip             # Archive format (zip/tar)
      archive_name: site-info         # Archive filename
      archive_stop_on_violation: false  # Continue on violations

Usage Examples

Meta Plugin Usage

Directory Structure

docs/
├── .meta.yml                 # Root metadata
├── api/
│   ├── .meta.yml            # API section metadata
│   ├── authentication.md
│   └── endpoints.md
└── guides/
    ├── .meta.yml            # Guides section metadata
    └── getting-started.md

Root Metadata (.meta.yml)

authors:
  - Technical Writing Team
tags:
  - documentation
template: base.html

Section Metadata (api/.meta.yml)

title: API Documentation
description: Complete API reference and guides
tags:
  - api
  - reference
template: api.html

Group Plugin Usage

Development Configuration

plugins:
  - material/group:
      plugins:
        - group: core
          plugins:
            - search
            - material/search
        - group: content
          plugins:
            - material/blog
            - material/tags
        - group: development
          enabled: !ENV [DEBUG, false]
          plugins:
            - material/info

Offline Plugin Usage

Basic Offline Support

plugins:
  - material/offline

theme:
  name: material
  features:
    - content.code.copy
    - navigation.instant  # Works with offline plugin

Advanced Offline Configuration

plugins:
  - material/offline

extra:
  manifest: manifest.json  # PWA manifest
  
theme:
  name: material
  features:
    - navigation.instant
    - navigation.tracking

Info Plugin Usage

Development Info Gathering

plugins:
  - material/info:
      archive: true
      archive_name: debug-info
      archive_stop_on_violation: false

Production Info Monitoring

plugins:
  - material/info:
      archive: false  # Don't create archives in production

Plugin APIs

Meta Plugin API

class MetaPlugin(BasePlugin[MetaConfig]):
    """Meta plugin for metadata management."""
    
    def on_files(self, files, *, config):
        """Process metadata files."""
    
    @event_priority(50)
    def on_page_markdown(self, markdown, *, page, config, files):
        """Inject metadata into page markdown."""

Group Plugin API

class GroupPlugin(BasePlugin[GroupConfig]):
    """Group plugin for plugin organization."""
    
    supports_multiple_instances = True
    
    def on_startup(self, *, command, dirty):
        """Initialize plugin groups."""
    
    @event_priority(150)
    def on_config(self, config):
        """Configure plugin groups."""

Offline Plugin API

class OfflinePlugin(BasePlugin[OfflineConfig]):
    """Offline plugin for progressive web app functionality."""
    
    def on_config(self, config):
        """Configure offline functionality."""
    
    @event_priority(-100)
    def on_post_build(self, *, config):
        """Generate service worker and offline assets."""

Info Plugin API

class InfoPlugin(BasePlugin[InfoConfig]):
    """Info plugin for environment information gathering."""
    
    def on_startup(self, *, command, dirty):
        """Gather startup information."""
    
    @event_priority(100)
    def on_config(self, config):
        """Configure info collection."""

Configuration Schemas

Meta Plugin Schema

class MetaConfig(Config):
    """Configuration options for the meta plugin."""
    
    enabled = Type(bool, default=True)
    meta_file = Type(str, default="**/.meta.yml")
    meta_file_recursive = Type(bool, default=True)
    meta_file_inherit = Type(bool, default=True)

Group Plugin Schema

class GroupConfig(Config):
    """Configuration options for the group plugin."""
    
    enabled = Type(bool, default=True)
    plugins = Type(list, default=[])

Offline Plugin Schema

class OfflineConfig(Config):
    """Configuration options for the offline plugin."""
    
    enabled = Type(bool, default=True)

Info Plugin Schema

class InfoConfig(Config):
    """Configuration options for the info plugin."""
    
    enabled = Type(bool, default=True)
    archive = Type(bool, default=True)
    archive_format = Choice(['zip', 'tar'], default='zip')
    archive_name = Type(str, default='site-info')
    archive_stop_on_violation = Type(bool, default=True)

Integration Examples

Complete Plugin Stack

plugins:
  # Core functionality
  - search
  - material/search:
      lang: en
  
  # Content management
  - material/meta:
      meta_file: "**/.meta.yml"
  - material/tags:
      tags_file: tags.md
  - material/blog:
      blog_dir: blog
  
  # Privacy and social
  - material/privacy:
      external_assets: bundle
  - material/social:
      cards_layout_options:
        background_color: "#1976D2"
  
  # Utility plugins
  - material/group:
      plugins:
        - group: development
          enabled: !ENV [DEBUG, false]
          plugins:
            - material/info
  - material/offline

Conditional Plugin Loading

plugins:
  - material/group:
      plugins:
        - group: production
          enabled: !ENV [PRODUCTION, false]
          plugins:
            - material/privacy
            - material/social
            - material/offline
        - group: development
          enabled: !ENV [DEBUG, false]
          plugins:
            - material/info:
                archive: true

Install with Tessl CLI

npx tessl i tessl/pypi-mkdocs-material

docs

additional-plugins.md

theme-configuration.md

tile.json

tessl/pypi-mkdocs-material