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

Social Cards Plugin

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

Automated social media card generation with customizable layouts, fonts, and branding. The social plugin creates Open Graph and Twitter Card images for improved social media sharing, enhancing the visibility and engagement of documentation when shared on social platforms.

Capabilities

Basic Social Cards Setup

Core social cards configuration that enables automatic image generation for social media sharing.

plugins:
  - material/social:
      enabled: true                    # Enable social cards (default: true)
      cache_dir: .cache/plugin/social  # Cache directory for generated cards
      cards: true                     # Generate social cards (default: true)
      cards_dir: assets/images/social  # Output directory for cards

Layout Configuration

Customizable card layouts with built-in templates and custom layout support.

plugins:
  - material/social:
      cards_layout_dir: layouts        # Custom layouts directory
      cards_layout: default           # Default layout template
      cards_layout_options:
        background_color: "#0F1419"   # Card background color
        color: "#FFFFFF"              # Text color
        font_family: Roboto           # Font family
        logo: assets/logo.png         # Logo image path

Typography and Fonts

Font configuration for social card text rendering with support for custom fonts.

plugins:
  - material/social:
      cards_layout_options:
        font_family: Roboto           # Primary font
        font_variant: Regular         # Font variant
        font_family_header: Roboto    # Header font
        font_variant_header: Bold     # Header font variant

Color Theming

Comprehensive color customization for social card appearance.

plugins:
  - material/social:
      cards_layout_options:
        background_color: "#2D2D2D"   # Background color
        background_image: bg.png      # Background image
        color: "#FFFFFF"              # Primary text color
        color_header: "#FF6B35"       # Header text color
        color_accent: "#FF6B35"       # Accent color

Logo and Branding

Brand integration with logo placement and styling options.

plugins:
  - material/social:
      cards_layout_options:
        logo: assets/logo.png         # Logo image path
        logo_variant: light           # Logo variant (light/dark)
        logo_size: 64                 # Logo size in pixels
        logo_position: top-right      # Logo position

Usage Examples

Basic Social Cards

plugins:
  - material/social

Custom Branded Cards

plugins:
  - material/social:
      cards_layout_options:
        background_color: "#1E88E5"
        color: "#FFFFFF"
        font_family: "Open Sans"
        logo: assets/company-logo.png

Advanced Corporate Branding

plugins:
  - material/social:
      cards_dir: assets/social
      cards_layout: corporate
      cards_layout_options:
        background_image: assets/social-bg.png
        background_color: "#1A1A1A"
        color: "#FFFFFF"
        color_header: "#00D4FF"
        font_family: "Source Sans Pro"
        font_variant: "SemiBold"
        font_family_header: "Source Sans Pro"
        font_variant_header: "Bold"
        logo: assets/brand-logo.svg
        logo_variant: light
        logo_size: 72

Minimalist Design

plugins:
  - material/social:
      cards_layout_options:
        background_color: "#FFFFFF"
        color: "#333333"
        color_header: "#1976D2"
        font_family: "Inter"
        font_variant: "Regular"

Custom Layouts

Create custom social card layouts using Jinja2 templates in the layouts directory.

Custom Layout Template

<!-- layouts/custom.html -->
<svg width="1200" height="630" xmlns="http://www.w3.org/2000/svg">
  <!-- Background -->
  <rect width="1200" height="630" fill="{{ config.background_color | default('#2D2D2D') }}"/>
  
  <!-- Logo -->
  {% if config.logo %}
  <image href="{{ config.logo }}" x="60" y="60" width="120" height="120"/>
  {% endif %}
  
  <!-- Title -->
  <text x="60" y="300" fill="{{ config.color_header | default('#FFFFFF') }}" 
        font-family="{{ config.font_family | default('Roboto') }}" 
        font-size="48" font-weight="bold">
    {{ page.title }}
  </text>
  
  <!-- Description -->
  <text x="60" y="360" fill="{{ config.color | default('#CCCCCC') }}" 
        font-family="{{ config.font_family | default('Roboto') }}" 
        font-size="24">
    {{ page.meta.description | default(config.site_description) }}
  </text>
  
  <!-- URL -->
  <text x="60" y="550" fill="{{ config.color_accent | default('#FF6B35') }}" 
        font-family="{{ config.font_family | default('Roboto') }}" 
        font-size="20">
    {{ config.site_url }}{{ page.url }}
  </text>
</svg>

Using Custom Layout

plugins:
  - material/social:
      cards_layout_dir: layouts
      cards_layout: custom
      cards_layout_options:
        background_color: "#1E3A8A"
        color: "#F3F4F6"
        color_header: "#FBBF24"
        color_accent: "#10B981"
        logo: assets/logo.svg

Page-Level Configuration

Override social card settings for individual pages using page metadata.

Page Frontmatter

---
title: Custom Page Title
description: Custom page description for social sharing
social:
  cards: true
  cards_layout: special
  cards_layout_options:
    background_color: "#FF0000"
---

# Page Content

Integration with Meta Tags

The social plugin automatically generates appropriate meta tags for social sharing.

Generated Meta Tags

<!-- Open Graph -->
<meta property="og:type" content="website">
<meta property="og:title" content="Page Title">
<meta property="og:description" content="Page description">
<meta property="og:image" content="https://example.com/assets/images/social/page.png">
<meta property="og:url" content="https://example.com/page/">

<!-- Twitter Cards -->
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="Page Title">
<meta name="twitter:description" content="Page description">
<meta name="twitter:image" content="https://example.com/assets/images/social/page.png">

Plugin API

class SocialPlugin(BasePlugin[SocialConfig]):
    """Social cards plugin for generating social media sharing images."""
    
    def on_config(self, config):
        """Configure social plugin settings."""
    
    def on_page_content(self, html, page, config, files):
        """Process page content for social card generation."""
    
    def on_post_build(self, config):
        """Finalize social card generation."""

Configuration Schema

class SocialConfig(Config):
    """Configuration options for the social plugin."""
    
    enabled = Type(bool, default=True)
    cards = Type(bool, default=True)
    cards_dir = Type(str, default="assets/images/social")
    cards_layout_dir = Optional(Type(str))
    cards_layout = Type(str, default="default")
    cards_layout_options = Type(dict, default={})

Install with Tessl CLI