CtrlK
BlogDocsLog inGet started
Tessl Logo

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

tags-plugin.mddocs/

Tags Plugin

Tag-based content organization with automatic tag pages, tag clouds, and tag-based navigation. The tags plugin enables content discovery through topic-based categorization, creating an intuitive taxonomy system for documentation.

Capabilities

Basic Tags Setup

Core tags configuration that enables tag-based content organization and automatic tag page generation.

plugins:
  - material/tags:
      enabled: true              # Enable tags plugin (default: true)
      tags: true                # Generate tag functionality (default: true)
      tags_slugify: !!python/name:pymdownx.slugs.slugify  # Tag slug generation
      tags_slugify_separator: "-"  # Tag slug separator
      tags_allowed: []          # Allowed tags list (empty = all allowed)

Tag Index Configuration

Customizable tag index page with listing and organization options.

plugins:
  - material/tags:
      tags_file: tags.md            # Tag index file path
      tags_name: "Tags"             # Tag index page name
      tags_template: "tags.html"    # Custom tag template
      tags_hierarchy: true          # Enable hierarchical tags
      tags_slugify: !!python/name:pymdownx.slugs.slugify
      tags_slugify_separator: "-"   # Tag slug separator

Tag Pages Configuration

Individual tag pages showing all content with specific tags.

plugins:
  - material/tags:
      tags_extra_files:
        compatibility.md:
          - compatibility         # Tag file mapping
        web.md:
          - html
          - css
          - javascript
      tags_allowed: []            # Restricted tag list (empty = all allowed)

Tag Appearance and Styling

Tag visual presentation and styling options.

plugins:
  - material/tags:
      tags_compare: case_sensitive    # Tag comparison mode
      tags_compare_reverse: false     # Reverse tag comparison
      tags_hierarchy: false           # Hierarchical tag display

Usage Examples

Basic Tags Implementation

plugins:
  - material/tags:
      tags_file: tags.md

Advanced Tag Organization

plugins:
  - material/tags:
      tags_file: reference/tags.md
      tags_extra_files:
        api.md:
          - api
          - reference
        tutorials.md:
          - tutorial
          - guide
        examples.md:
          - example
          - demo
      tags_allowed:
        - api
        - tutorial
        - guide
        - reference
        - example
        - demo
        - advanced
        - beginner

Hierarchical Tags

plugins:
  - material/tags:
      tags_file: tags.md
      tags_hierarchy: true
      tags_slugify: !!python/name:pymdownx.slugs.slugify
      tags_compare: case_insensitive

Minimal Tags

plugins:
  - material/tags

Page-Level Tag Usage

Add tags to individual pages using frontmatter metadata.

Page Frontmatter

---
title: Getting Started Guide
tags:
  - tutorial
  - beginner
  - setup
  - installation
---

# Getting Started Guide

This guide will help you get started...

Tag Syntax Variations

---
# Single tag
tags: tutorial

# Multiple tags (list format)
tags:
  - tutorial
  - api
  - advanced

# Multiple tags (inline format)
tags: [tutorial, api, advanced]
---

Tag Index Page

Create a dedicated tags index page to display all available tags and their associated content.

Tags Index Template

---
template: tags.html
title: Tags
---

# Tags

Explore content by topic using the tags below.

Custom Tags Page

---
title: Documentation Tags
---

# Content by Topic

Browse our documentation by category:

## API Documentation
- [API Reference](../api/) `api` `reference`
- [Authentication](../auth/) `api` `auth` `security`

## Tutorials
- [Getting Started](../getting-started/) `tutorial` `beginner`
- [Advanced Usage](../advanced/) `tutorial` `advanced`

## Examples
- [Code Examples](../examples/) `example` `demo`
- [Use Cases](../use-cases/) `example` `tutorial`

Tag Display Options

Control how tags appear on pages and in navigation.

Theme Integration

theme:
  name: material
  features:
    - content.tags.link      # Enable tag links

Tag Styling

Tags automatically inherit theme colors and can be styled with CSS:

.md-tag {
  background-color: var(--md-primary-fg-color);
  color: var(--md-primary-bg-color);
}

.md-tag:hover {
  background-color: var(--md-accent-fg-color);
}

Tag Hierarchy

Organize tags hierarchically for better content structure.

Hierarchical Tag Structure

---
tags:
  - programming/python
  - programming/web
  - framework/django
  - level/intermediate
---

Tag Filtering

plugins:
  - material/tags:
      tags_allowed:
        - programming/python
        - programming/javascript
        - programming/web
        - framework/django
        - framework/react
        - level/beginner
        - level/intermediate
        - level/advanced

Plugin API

class TagsPlugin(BasePlugin[TagsConfig]):
    """Tags plugin for content organization and discovery."""
    
    supports_multiple_instances = True
    
    def on_startup(self, *, command, **kwargs) -> None:
        """Initialize tags plugin on startup."""
    
    def on_config(self, config: MkDocsConfig) -> None:
        """Configure tags plugin settings."""
    
    @event_priority(-50)
    def on_page_markdown(self, markdown: str, *, page: Page, config: MkDocsConfig, **kwargs) -> str:
        """Process page markdown for tag extraction."""
    
    @event_priority(100)
    def on_env(self, env: Environment, *, config: MkDocsConfig, **kwargs) -> None:
        """Configure template environment for tags."""
    
    def on_page_context(self, context: TemplateContext, *, page: Page, **kwargs) -> None:
        """Add tag context to page rendering."""

Configuration Schema

class TagsConfig(Config):
    """Configuration options for the tags plugin."""
    
    enabled = Type(bool, default=True)
    tags = Type(bool, default=True)
    tags_file = Optional(Type(str))
    tags_name = Type(str, default="Tags")
    tags_template = Optional(Type(str))
    tags_extra_files = Type(dict, default={})
    tags_allowed = Type(list, default=[])
    tags_compare = Choice(['case_sensitive', 'case_insensitive'], default='case_sensitive')
    tags_compare_reverse = Type(bool, default=False)
    tags_hierarchy = Type(bool, default=False)
    tags_slugify = Type(callable, default=None)
    tags_slugify_separator = Type(str, default='-')

Tag Cloud Generation

The plugin can generate tag clouds showing tag frequency and importance.

Tag Statistics

# Available in template context
tag_stats = {
    'tutorial': {'count': 15, 'pages': [...]},
    'api': {'count': 8, 'pages': [...]},
    'example': {'count': 12, 'pages': [...]}
}

Template Variables

<!-- Available in tags template -->
{{ tags }}          <!-- List of all tags -->
{{ tag_stats }}     <!-- Tag usage statistics -->
{{ pages_by_tag }}  <!-- Pages organized by tag -->

Install with Tessl CLI

npx tessl i tessl/pypi-mkdocs-material

docs

additional-plugins.md

blog-plugin.md

index.md

privacy-plugin.md

search-plugin.md

social-plugin.md

tags-plugin.md

theme-configuration.md

tile.json