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

Blog Plugin

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

Comprehensive blogging functionality that transforms MkDocs into a full-featured blog platform. The blog plugin provides posts, archives, categories, tags, authors, pagination, reading time estimation, and social integration.

Capabilities

Basic Blog Setup

Core blog configuration that establishes the blog structure and basic functionality.

plugins:
  - material/blog:
      enabled: true              # Enable blog plugin (default: true)
      blog_dir: blog            # Blog directory (default: blog) 
      blog_toc: false           # Show TOC for blog pages (default: false)

Post Configuration

Comprehensive post handling including URL structure, date formatting, and content processing.

plugins:
  - material/blog:
      # Post directory and structure
      post_dir: "{blog}/posts"              # Posts directory pattern
      post_url_format: "{date}/{slug}"      # Post URL structure
      post_url_date_format: "yyyy/MM/dd"    # Date format in URLs
      post_date_format: "long"              # Display date format
      
      # Post processing
      post_slugify: !!python/name:pymdownx.slugs.slugify
      post_slugify_separator: "-"           # Slug separator
      post_excerpt: "optional"              # Excerpt requirement (optional/required)
      post_excerpt_separator: "<!-- more -->"  # Excerpt separator
      post_excerpt_max_authors: 1           # Max authors in excerpt
      post_excerpt_max_categories: 5        # Max categories in excerpt
      
      # Reading time
      post_readtime: true                   # Show reading time (default: true)
      post_readtime_words_per_minute: 265   # Reading speed calculation

Archive Configuration

Automatic archive generation with date-based organization and navigation.

plugins:
  - material/blog:
      # Archive settings
      archive: true                         # Enable archive (default: true)
      archive_name: "blog.archive"          # Archive page name
      archive_date_format: "yyyy"           # Archive date display format
      archive_url_date_format: "yyyy"       # Archive URL date format
      archive_url_format: "archive/{date}"  # Archive URL structure
      archive_toc: false                    # Archive page TOC

Category Configuration

Category-based content organization with automatic category pages and navigation.

plugins:
  - material/blog:
      # Category settings
      categories: true                      # Enable categories (default: true)
      categories_name: "blog.categories"    # Categories page name
      categories_url_format: "category/{slug}"  # Category URL structure
      categories_slugify: !!python/name:pymdownx.slugs.slugify
      categories_slugify_separator: "-"     # Category slug separator
      categories_allowed: []                # Allowed categories list
      categories_toc: false                 # Category page TOC

Pagination Configuration

Paginated blog views with configurable page sizes and navigation.

plugins:
  - material/blog:
      # Pagination settings
      pagination: true                      # Enable pagination (default: true)
      pagination_per_page: 10              # Posts per page
      pagination_url_format: "page/{page}" # Pagination URL structure
      pagination_format: "$link_first $link_previous ~2~ $link_next $link_last"
      pagination_keep_content: false       # Keep content on paginated pages

Authors Configuration

Author management with profiles, social links, and author pages.

plugins:
  - material/blog:
      # Authors settings
      authors: true                         # Enable authors (default: true)
      authors_file: "{blog}/.authors.yml"  # Authors configuration file
      authors_profiles: true                # Enable author profiles
      authors_profiles_name: "blog.authors"  # Authors page name
      authors_profiles_url_format: "author/{slug}"  # Author URL structure
      authors_profiles_toc: false           # Author page TOC

Draft and Visibility

Content visibility control including drafts and publication management.

plugins:
  - material/blog:
      # Draft settings
      draft: false                          # Include drafts (default: false)
      draft_on_serve: true                  # Show drafts during serve
      draft_if_future_date: false          # Draft posts with future dates

Usage Examples

Basic Blog Setup

plugins:
  - material/blog:
      blog_dir: blog
      post_excerpt: required
      categories: true
      archive: true

Advanced Blog Configuration

plugins:
  - material/blog:
      # Blog structure
      blog_dir: articles
      post_dir: "{blog}/posts"
      post_url_format: "{categories[0]}/{date}/{slug}"
      post_url_date_format: "yyyy/MM/dd"
      
      # Content processing
      post_excerpt: required
      post_excerpt_separator: "<!-- more -->"
      post_readtime: true
      post_readtime_words_per_minute: 250
      
      # Organization
      categories: true
      categories_allowed:
        - Technology
        - Documentation
        - Tutorials
      archive: true
      archive_date_format: "MMMM yyyy"
      
      # Pagination
      pagination: true
      pagination_per_page: 5
      
      # Authors
      authors: true
      authors_file: "{blog}/.authors.yml"
      authors_profiles: true

Author Configuration File

Create .authors.yml in your blog directory:

authors:
  john:
    name: John Doe
    description: Technical Writer
    avatar: https://example.com/avatar.jpg
    url: https://johndoe.com
    social:
      - icon: fontawesome/brands/github
        link: https://github.com/johndoe
      - icon: fontawesome/brands/twitter
        link: https://twitter.com/johndoe
  
  jane:
    name: Jane Smith
    description: Software Engineer
    avatar: https://example.com/jane.jpg

Blog Post Format

Create posts in your posts directory with proper frontmatter:

---
title: My Blog Post
description: A short description of the post
authors:
  - john
  - jane
categories:
  - Technology
  - Tutorials
date: 2023-12-01
draft: false
---

# My Blog Post

This is the post content.

<!-- more -->

This content appears after the excerpt separator.

Minimal Blog

plugins:
  - material/blog

Plugin API

class BlogPlugin(BasePlugin[BlogConfig]):
    """Blog plugin for creating blog functionality in MkDocs Material."""
    supports_multiple_instances = True
    
    def on_startup(self, *, command, dirty):
        """Determine whether we're serving the site."""
    
    def on_config(self, config):
        """Initialize authors and set defaults."""
    
    @event_priority(-50)
    def on_files(self, files, *, config):
        """Resolve and load posts and generate views (run later)."""
    
    @event_priority(-50)
    def on_nav(self, nav, *, config, files):
        """Attach posts and views to navigation (run later)."""
    
    @event_priority(-50)
    def on_page_markdown(self, markdown, *, page, config, files):
        """Prepare post for rendering (run later)."""
    
    def on_page_content(self, html, *, page, config, files):
        """Process posts."""
    
    def on_env(self, env, *, config, files):
        """Register template filters for plugin."""
    
    @event_priority(-100)
    def on_page_context(self, context, *, page, config, nav):
        """Prepare view for rendering (run latest)."""
    
    def on_shutdown(self):
        """Remove temporary directory on shutdown."""

Install with Tessl CLI