0
# Social Cards Plugin
1

2
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.
3

4
## Capabilities
5

6
### Basic Social Cards Setup
7

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

10
```yaml { .api }
11
plugins:
12
  - material/social:
13
      enabled: true                    # Enable social cards (default: true)
14
      cache_dir: .cache/plugin/social  # Cache directory for generated cards
15
      cards: true                     # Generate social cards (default: true)
16
      cards_dir: assets/images/social  # Output directory for cards
17
```
18

19
### Layout Configuration
20

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

23
```yaml { .api }
24
plugins:
25
  - material/social:
26
      cards_layout_dir: layouts        # Custom layouts directory
27
      cards_layout: default           # Default layout template
28
      cards_layout_options:
29
        background_color: "#0F1419"   # Card background color
30
        color: "#FFFFFF"              # Text color
31
        font_family: Roboto           # Font family
32
        logo: assets/logo.png         # Logo image path
33
```
34

35
### Typography and Fonts
36

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

39
```yaml { .api }
40
plugins:
41
  - material/social:
42
      cards_layout_options:
43
        font_family: Roboto           # Primary font
44
        font_variant: Regular         # Font variant
45
        font_family_header: Roboto    # Header font
46
        font_variant_header: Bold     # Header font variant
47
```
48

49
### Color Theming
50

51
Comprehensive color customization for social card appearance.
52

53
```yaml { .api }
54
plugins:
55
  - material/social:
56
      cards_layout_options:
57
        background_color: "#2D2D2D"   # Background color
58
        background_image: bg.png      # Background image
59
        color: "#FFFFFF"              # Primary text color
60
        color_header: "#FF6B35"       # Header text color
61
        color_accent: "#FF6B35"       # Accent color
62
```
63

64
### Logo and Branding
65

66
Brand integration with logo placement and styling options.
67

68
```yaml { .api }
69
plugins:
70
  - material/social:
71
      cards_layout_options:
72
        logo: assets/logo.png         # Logo image path
73
        logo_variant: light           # Logo variant (light/dark)
74
        logo_size: 64                 # Logo size in pixels
75
        logo_position: top-right      # Logo position
76
```
77

78
## Usage Examples
79

80
### Basic Social Cards
81

82
```yaml
83
plugins:
84
  - material/social
85
```
86

87
### Custom Branded Cards
88

89
```yaml
90
plugins:
91
  - material/social:
92
      cards_layout_options:
93
        background_color: "#1E88E5"
94
        color: "#FFFFFF"
95
        font_family: "Open Sans"
96
        logo: assets/company-logo.png
97
```
98

99
### Advanced Corporate Branding
100

101
```yaml
102
plugins:
103
  - material/social:
104
      cards_dir: assets/social
105
      cards_layout: corporate
106
      cards_layout_options:
107
        background_image: assets/social-bg.png
108
        background_color: "#1A1A1A"
109
        color: "#FFFFFF"
110
        color_header: "#00D4FF"
111
        font_family: "Source Sans Pro"
112
        font_variant: "SemiBold"
113
        font_family_header: "Source Sans Pro"
114
        font_variant_header: "Bold"
115
        logo: assets/brand-logo.svg
116
        logo_variant: light
117
        logo_size: 72
118
```
119

120
### Minimalist Design
121

122
```yaml
123
plugins:
124
  - material/social:
125
      cards_layout_options:
126
        background_color: "#FFFFFF"
127
        color: "#333333"
128
        color_header: "#1976D2"
129
        font_family: "Inter"
130
        font_variant: "Regular"
131
```
132

133
## Custom Layouts
134

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

137
### Custom Layout Template
138

139
```html
140
<!-- layouts/custom.html -->
141
<svg width="1200" height="630" xmlns="http://www.w3.org/2000/svg">
142
  <!-- Background -->
143
  <rect width="1200" height="630" fill="{{ config.background_color | default('#2D2D2D') }}"/>
144
  
145
  <!-- Logo -->
146
  {% if config.logo %}
147
  <image href="{{ config.logo }}" x="60" y="60" width="120" height="120"/>
148
  {% endif %}
149
  
150
  <!-- Title -->
151
  <text x="60" y="300" fill="{{ config.color_header | default('#FFFFFF') }}" 
152
        font-family="{{ config.font_family | default('Roboto') }}" 
153
        font-size="48" font-weight="bold">
154
    {{ page.title }}
155
  </text>
156
  
157
  <!-- Description -->
158
  <text x="60" y="360" fill="{{ config.color | default('#CCCCCC') }}" 
159
        font-family="{{ config.font_family | default('Roboto') }}" 
160
        font-size="24">
161
    {{ page.meta.description | default(config.site_description) }}
162
  </text>
163
  
164
  <!-- URL -->
165
  <text x="60" y="550" fill="{{ config.color_accent | default('#FF6B35') }}" 
166
        font-family="{{ config.font_family | default('Roboto') }}" 
167
        font-size="20">
168
    {{ config.site_url }}{{ page.url }}
169
  </text>
170
</svg>
171
```
172

173
### Using Custom Layout
174

175
```yaml
176
plugins:
177
  - material/social:
178
      cards_layout_dir: layouts
179
      cards_layout: custom
180
      cards_layout_options:
181
        background_color: "#1E3A8A"
182
        color: "#F3F4F6"
183
        color_header: "#FBBF24"
184
        color_accent: "#10B981"
185
        logo: assets/logo.svg
186
```
187

188
## Page-Level Configuration
189

190
Override social card settings for individual pages using page metadata.
191

192
### Page Frontmatter
193

194
```markdown
195
---
196
title: Custom Page Title
197
description: Custom page description for social sharing
198
social:
199
  cards: true
200
  cards_layout: special
201
  cards_layout_options:
202
    background_color: "#FF0000"
203
---
204

205
# Page Content
206
```
207

208
## Integration with Meta Tags
209

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

212
### Generated Meta Tags
213

214
```html
215
<!-- Open Graph -->
216
<meta property="og:type" content="website">
217
<meta property="og:title" content="Page Title">
218
<meta property="og:description" content="Page description">
219
<meta property="og:image" content="https://example.com/assets/images/social/page.png">
220
<meta property="og:url" content="https://example.com/page/">
221

222
<!-- Twitter Cards -->
223
<meta name="twitter:card" content="summary_large_image">
224
<meta name="twitter:title" content="Page Title">
225
<meta name="twitter:description" content="Page description">
226
<meta name="twitter:image" content="https://example.com/assets/images/social/page.png">
227
```
228

229
## Plugin API
230

231
```python { .api }
232
class SocialPlugin(BasePlugin[SocialConfig]):
233
    """Social cards plugin for generating social media sharing images."""
234
    
235
    def on_config(self, config):
236
        """Configure social plugin settings."""
237
    
238
    def on_page_content(self, html, page, config, files):
239
        """Process page content for social card generation."""
240
    
241
    def on_post_build(self, config):
242
        """Finalize social card generation."""
243
```
244

245
## Configuration Schema
246

247
```python { .api }
248
class SocialConfig(Config):
249
    """Configuration options for the social plugin."""
250
    
251
    enabled = Type(bool, default=True)
252
    cards = Type(bool, default=True)
253
    cards_dir = Type(str, default="assets/images/social")
254
    cards_layout_dir = Optional(Type(str))
255
    cards_layout = Type(str, default="default")
256
    cards_layout_options = Type(dict, default={})
257
```