or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

additional-plugins.mdblog-plugin.mdindex.mdprivacy-plugin.mdsearch-plugin.mdsocial-plugin.mdtags-plugin.mdtheme-configuration.md
tile.json

tessl/pypi-mkdocs-material

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/mkdocs-material@9.6.x

To install, run

npx @tessl/cli install tessl/pypi-mkdocs-material@9.6.0

index.mddocs/

MkDocs Material

A powerful documentation framework that provides a modern, responsive Material Design theme for MkDocs static site generators. MkDocs Material transforms Markdown documentation into professional static sites with advanced features including full-text search, mobile optimization, syntax highlighting, and support for over 60 languages.

Package Information

  • Package Name: mkdocs-material
  • Package Type: pypi
  • Language: Python
  • Installation: pip install mkdocs-material

Core Imports

MkDocs Material is configured through MkDocs configuration files and doesn't require Python imports for basic usage. The theme and plugins are activated via mkdocs.yml configuration.

Basic Usage

Theme Configuration

Configure the Material theme in your mkdocs.yml:

theme:
  name: material
  features:
    - navigation.tabs
    - navigation.sections
    - navigation.expand
    - navigation.top
    - search.highlight
    - search.share
  palette:
    - scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - scheme: slate
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: Switch to light mode

Plugin Configuration

Enable Material plugins in your mkdocs.yml:

plugins:
  - search
  - material/search:
      lang: en
  - material/tags:
      tags_file: tags.md
  - material/blog:
      blog_dir: blog
      post_excerpt: required

Architecture

MkDocs Material extends the MkDocs architecture with:

  • Theme System: Jinja2-based templates with Material Design components
  • Plugin Framework: Built-in plugins extending MkDocs functionality
  • Asset Pipeline: TypeScript/JavaScript build system for frontend assets
  • Configuration Layer: YAML-based configuration for theme and plugin options

The architecture enables complete customization through template overrides, CSS variables, custom plugins, and extensive configuration options while maintaining compatibility with the broader MkDocs ecosystem.

Capabilities

Theme Configuration

Complete theme customization including colors, fonts, navigation patterns, and feature toggles. The theme provides dozens of configuration options for visual appearance and user interface behavior.

theme:
  name: material
  language: en
  direction: ltr
  features: []
  palette: {}
  font: {}
  icon: {}
  logo: string
  favicon: string
  custom_dir: string

Theme Configuration

Blog Plugin

Comprehensive blogging functionality with posts, archives, categories, tags, authors, pagination, and social integration. Transforms MkDocs into a full-featured blog platform.

class BlogPlugin(BasePlugin[BlogConfig]):
    supports_multiple_instances = True
    
    def on_startup(self, *, command, dirty): ...
    def on_config(self, config): ...
    @event_priority(-50)
    def on_files(self, files, *, config): ...
    @event_priority(-50)
    def on_nav(self, nav, *, config, files): ...
    @event_priority(-50)
    def on_page_markdown(self, markdown, *, page, config, files): ...
    def on_page_content(self, html, *, page, config, files): ...
    def on_env(self, env, *, config, files): ...
    @event_priority(-100)
    def on_page_context(self, context, *, page, config, nav): ...
    def on_shutdown(self): ...

Blog Plugin

Search Plugin

Advanced search functionality with language support, search highlighting, search suggestions, and configurable search pipeline. Provides instant client-side search across documentation.

class SearchPlugin(BasePlugin[SearchConfig]):
    def on_startup(self, *, command, dirty): ...
    def on_config(self, config): ...
    def on_page_context(self, context, *, page, config, nav): ...
    def on_post_build(self, *, config): ...
    def on_serve(self, server, *, config, builder): ...

Search Plugin

Social Cards Plugin

Automated social media card generation with customizable layouts, fonts, and branding. Creates Open Graph and Twitter Card images for improved social media sharing.

class SocialPlugin(BasePlugin[SocialConfig]):
    def on_config(self, config): ...
    def on_page_content(self, html, page, config, files): ...
    def on_post_build(self, config): ...

Social Cards Plugin

Tags Plugin

Tag-based content organization with automatic tag pages, tag clouds, and tag-based navigation. Enables content discovery through topic-based categorization.

class TagsPlugin(BasePlugin[TagsConfig]):
    supports_multiple_instances = True
    
    def on_startup(self, *, command, **kwargs) -> None: ...
    def on_config(self, config: MkDocsConfig) -> None: ...
    @event_priority(-50)
    def on_page_markdown(self, markdown: str, *, page: Page, config: MkDocsConfig, **kwargs) -> str: ...
    @event_priority(100)
    def on_env(self, env: Environment, *, config: MkDocsConfig, **kwargs) -> None: ...
    def on_page_context(self, context: TemplateContext, *, page: Page, **kwargs) -> None: ...

Tags Plugin

Privacy Plugin

Privacy compliance features including cookie consent, external asset localization, and GDPR compliance helpers. Ensures documentation sites meet privacy regulations.

class PrivacyPlugin(BasePlugin[PrivacyConfig]):
    def on_config(self, config): ...
    @event_priority(-100)
    def on_files(self, files, *, config): ...
    @event_priority(-100)
    def on_page_content(self, html, *, page, config, files): ...
    def on_env(self, env, *, config, files): ...
    @event_priority(-50)
    def on_post_template(self, output_content, *, template_name, config): ...
    @event_priority(-50)
    def on_post_page(self, output, *, page, config): ...
    @event_priority(50)
    def on_post_build(self, *, config): ...

Privacy Plugin

Emoji Extension

Markdown extension providing emoji and icon rendering with custom icon integration and Material Design icon support.

# Extension functions
def twemoji(options: object, md: Markdown): ...
def to_svg(
    index: str, shortname: str, alias: str, uc: str | None, alt: str,
    title: str, category: str, options: object, md: Markdown
): ...

# Markdown extension configuration
markdown_extensions:
  - material.extensions.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
      options:
        custom_icons:
          - overrides/.icons

Additional Plugins

Meta, Group, Offline, and Info plugins provide specialized functionality for metadata management, plugin grouping, offline support, and environment information gathering.

class MetaPlugin(BasePlugin[MetaConfig]):
    def on_files(self, files, *, config): ...
    @event_priority(50)
    def on_page_markdown(self, markdown, *, page, config, files): ...

class GroupPlugin(BasePlugin[GroupConfig]):
    supports_multiple_instances = True
    
    def on_startup(self, *, command, dirty): ...
    @event_priority(150)
    def on_config(self, config): ...

class OfflinePlugin(BasePlugin[OfflineConfig]):
    def on_config(self, config): ...
    @event_priority(-100)
    def on_post_build(self, *, config): ...

class InfoPlugin(BasePlugin[InfoConfig]):
    def on_startup(self, *, command, dirty): ...
    @event_priority(100)
    def on_config(self, config): ...

Additional Plugins

Types

from mkdocs.config.defaults import MkDocsConfig
from mkdocs.structure.files import Files
from mkdocs.structure.nav import Navigation
from mkdocs.structure.pages import Page
from mkdocs.plugins import BasePlugin, event_priority
from jinja2 import Environment, TemplateContext
from markdown import Markdown
from typing import Dict, Any, Union

# Theme configuration types
ThemeConfig = Dict[str, Any]
PaletteConfig = Dict[str, Union[str, Dict[str, str]]]
FontConfig = Dict[str, str]
IconConfig = Dict[str, str]

# Plugin configuration types
BlogConfig = Dict[str, Any]
SearchConfig = Dict[str, Any]
SocialConfig = Dict[str, Any]
TagsConfig = Dict[str, Any]
PrivacyConfig = Dict[str, Any]
MetaConfig = Dict[str, Any]
GroupConfig = Dict[str, Any]
OfflineConfig = Dict[str, Any]
InfoConfig = Dict[str, Any]