Social Media Cards

Automatically generate beautiful social media preview cards for your documentation pages, ensuring great visibility when shared on social platforms.

Overview

Social media cards are automatically generated images that appear when your documentation links are shared on:

• Twitter - Summary cards with large images
• Facebook - Open Graph previews
• LinkedIn - Professional link previews
• Slack - Rich message attachments
• Discord - Embedded link previews

Configuration

Basic Setup

The social plugin is configured in mkdocs.yml:

plugins:
  - social:
      cards: true
      cards_layout: default
      cards_layout_options:
        background_color: "#1e2129"
        color: "#ffffff"
        font_family: "Roboto"

Prerequisites

Install required dependencies:

pip install pillow cairosvg

Set your site URL in mkdocs.yml:

site_url: https://your-domain.com

Card Layouts

Default Layout

The default layout includes:

• Site name and logo
• Page title
• Page description
• Background color/gradient

Example configuration:

plugins:
  - social:
      cards: true
      cards_layout: default
      cards_layout_options:
        background_color: "#2196F3"
        color: "#ffffff"
        font_family: "Roboto"

Custom Layouts

Create custom card layouts:

plugins:
  - social:
      cards: true
      cards_layout: custom
      cards_layout_dir: layouts
      cards_layout_options:
        background_image: assets/card-bg.png
        logo: assets/logo.png
        font_family: "Inter"

Directory structure:

layouts/
├── custom.yml
├── background.png
└── logo.png

Layout Options

Available options for customization:

Option	Description	Default
background_color	Card background color	#1e2129
color	Text color	#ffffff
font_family	Font for text	Roboto
logo	Path to logo file	Site logo
title_font_size	Title text size	48
description_font_size	Description text size	24

Per-Page Customization

Using Front Matter

Customize cards for individual pages:

---
title: Advanced Features
description: Learn about advanced MkDocs features
social:
  cards_layout: blog
  image: assets/images/advanced-features.png
---

# Advanced Features

Custom Images

Override generated cards with custom images:

---
title: Getting Started
image: assets/social/getting-started.png
---

Meta Tags

Add custom Open Graph and Twitter tags:

---
title: API Documentation
meta:
  - property: og:title
    content: "API Reference - MyProject"
  - property: og:description
    content: "Complete API documentation"
  - property: og:image
    content: "https://example.com/api-card.png"
  - name: twitter:card
    content: "summary_large_image"
  - name: twitter:title
    content: "API Reference"
  - name: twitter:description
    content: "Complete API documentation"
  - name: twitter:image
    content: "https://example.com/api-card.png"
---

Exclusions

Excluding Pages

Exclude specific pages from card generation:

plugins:
  - social:
      cards: true
      cards_exclude:
        - index.md
        - changelog.md
        - blog/drafts/*

Conditional Generation

Disable cards for development:

plugins:
  - social:
      cards: !ENV [ENABLE_SOCIAL_CARDS, true]

Advanced Configuration

Multiple Layouts

Define different layouts for different sections:

# In .meta.yml for blog directory
social:
  cards_layout: blog
  cards_layout_options:
    background_color: "#ff6b6b"
    font_family: "Georgia"

# In .meta.yml for docs directory  
social:
  cards_layout: technical
  cards_layout_options:
    background_color: "#4ecdc4"
    font_family: "Monaco"

Dynamic Content

Use page variables in cards:

plugins:
  - social:
      cards: true
      cards_layout_options:
        title: "{{ page.title }} | {{ config.site_name }}"
        description: "{{ page.meta.description }}"
        author: "{{ page.meta.author }}"
        date: "{{ page.meta.date }}"

Custom Fonts

Add custom fonts:

plugins:
  - social:
      cards: true
      cards_layout_options:
        font_family: "CustomFont"
        font_path: "assets/fonts/CustomFont.ttf"

Theme Integration

Material Theme Colors

Use Material theme colors:

theme:
  palette:
    primary: indigo
    accent: amber

plugins:
  - social:
      cards: true
      cards_layout_options:
        background_color: "{{ config.theme.palette.primary }}"
        accent_color: "{{ config.theme.palette.accent }}"

Dark Mode Support

Different cards for dark mode:

plugins:
  - social:
      cards: true
      cards_layout: !ENV [THEME_MODE, "light"]
      cards_layout_options:
        background_color: !ENV [BG_COLOR, "#ffffff"]
        color: !ENV [TEXT_COLOR, "#000000"]

Performance

Caching

Generated cards are cached:

• Cards regenerate only when content changes
• Cache location: .cache/plugin/social/
• Clear cache: rm -rf .cache/

Build Optimization

Speed up builds:

plugins:
  - social:
      cards: true
      cards_cache_dir: .cache/social
      concurrent_limit: 8  # Parallel generation

Conditional Building

Disable for faster local builds:

# Local development
mkdocs serve

# Production build with cards
ENABLE_SOCIAL_CARDS=true mkdocs build

Testing Cards

Preview Tools

Test how cards appear:

1. Facebook Debugger: https://developers.facebook.com/tools/debug/
2. Twitter Card Validator: https://cards-dev.twitter.com/validator
3. LinkedIn Post Inspector: https://www.linkedin.com/post-inspector/

Local Testing

Preview generated cards:

# Build site
mkdocs build

# View generated cards
ls site/assets/images/social/

Debug Mode

Enable debug output:

plugins:
  - social:
      cards: true
      debug: true
      debug_on_build: true

Best Practices

1. Image Quality

• Use high-resolution logos
• Ensure text contrast
• Test on different backgrounds
• Keep file sizes reasonable

2. Content Guidelines

• Write compelling titles
• Keep descriptions concise
• Use consistent branding
• Include relevant keywords

3. Accessibility

• Ensure color contrast
• Use readable fonts
• Test with color blindness simulators
• Provide alt text

4. SEO Benefits

• Improve click-through rates
• Enhance brand recognition
• Increase social engagement
• Better search visibility

Examples

Blog Post Card

# blog/.meta.yml
social:
  cards_layout: blog
  cards_layout_options:
    background_image: assets/blog-bg.jpg
    overlay_color: "rgba(0,0,0,0.7)"
    author_position: "bottom-left"
    date_position: "bottom-right"

Documentation Card

# docs/.meta.yml
social:
  cards_layout: docs
  cards_layout_options:
    background_gradient: "linear-gradient(135deg, #667eea 0%, #764ba2 100%)"
    icon: "book"
    category: "top-right"

Product Card

# products/.meta.yml
social:
  cards_layout: product
  cards_layout_options:
    background_pattern: "circuit"
    highlight_color: "#00ff88"
    feature_list: true

Troubleshooting

Cards Not Generating

1. Check site_url is set
2. Verify dependencies installed
3. Check file permissions
4. Enable debug mode

Wrong Information

1. Clear cache directory
2. Check front matter
3. Verify meta tags
4. Rebuild site

Poor Quality

1. Increase image resolution
2. Check font rendering
3. Adjust colors
4. Test different layouts

Related Features

• Video Embedding - Embed videos with metadata
• SEO - Search engine optimization
• Meta Tags - Custom metadata