0
# Card Layouts
1

2
Displays content in card-based grid layouts with support for images, icons, links, and responsive columns. This Markdown extension provides card components for organizing content in visually appealing grid layouts, supporting both embedded and external data sources with extensive customization options.
3

4
## Capabilities
5

6
### Extension Configuration
7

8
Configure the cards extension with priority and link behavior options.
9

10
```python { .api }
11
class CardsExtension(Extension):
12
    """
13
    Markdown extension for card layout components.
14
    
15
    Configuration:
16
    - priority: Extension processing priority (default: 12)
17
    - blank_target: Whether to open links in new tab (default: False)
18
    """
19
    config = {
20
        "priority": [12, "The priority to be configured for the extension."],
21
        "blank_target": [False, 'Whether to generate links with target="_blank"'],
22
    }
23
    
24
    def extendMarkdown(self, md): ...
25
```
26

27
### Card Processing
28

29
The extension supports two processing modes for different data sources.
30

31
```python { .api }
32
class CardsEmbeddedProcessor(BaseCardsProcessor, EmbeddedBlockProcessor):
33
    """
34
    Block processor for embedded card data using ::cards:: syntax.
35
    """
36

37
class CardsSourceProcessor(BaseCardsProcessor, SourceBlockProcessor):
38
    """
39
    Block processor for external card data using [cards(...)] syntax.
40
    """
41

42
class BaseCardsProcessor:
43
    """
44
    Base class for card processors with common functionality.
45
    """
46
    @property
47
    def name(self) -> str:
48
        """Returns 'cards' as the processor name."""
49
    
50
    def norm_obj(self, obj):
51
        """
52
        Normalizes card data, converting image objects.
53
        
54
        Parameters:
55
        - obj: List of card item dictionaries
56
        """
57
    
58
    def build_html(self, parent, obj, props) -> None:
59
        """
60
        Builds HTML for card components.
61
        
62
        Parameters:
63
        - parent: Parent XML element
64
        - obj: List of card items
65
        - props: Configuration properties
66
        """
67
```
68

69
## Data Models
70

71
### Card Data Structures
72

73
```python { .api }
74
class CardItem:
75
    """
76
    Represents a single card item.
77
    
78
    Attributes:
79
    - title: Card title (required)
80
    - url: Optional link URL
81
    - content: Card content description
82
    - icon: Icon identifier (FontAwesome, image, or text)
83
    - key: Optional unique identifier
84
    - image: Optional card image
85
    """
86
    title: str
87
    url: Optional[str]
88
    content: Optional[str]
89
    icon: Optional[str]
90
    key: Optional[str]
91
    image: Optional[Image]
92

93
class Cards:
94
    """
95
    Represents a collection of card items.
96
    
97
    Attributes:
98
    - items: List of card items
99
    """
100
    items: List[CardItem]
101
```
102

103
### HTML Rendering
104

105
```python { .api }
106
class CardsViewOptions:
107
    """
108
    Configuration options for cards rendering.
109
    
110
    Attributes:
111
    - id: HTML ID attribute
112
    - class_name: CSS class name
113
    - cols: Number of columns in grid
114
    - image_bg: Whether to use images as backgrounds
115
    - blank_target: Whether to open links in new tab
116
    """
117
    id: Optional[str]
118
    class_name: Optional[str]
119
    cols: int
120
    image_bg: bool
121
    blank_target: bool
122

123
class CardsHTMLBuilder:
124
    """
125
    Builds HTML for card components.
126
    """
127
    def build_html(self, parent, cards: Cards) -> None:
128
        """
129
        Builds complete cards grid HTML structure.
130
        
131
        Parameters:
132
        - parent: Parent XML element
133
        - cards: Cards data to render
134
        """
135
    
136
    def build_item_html(self, parent, item: CardItem) -> None:
137
        """
138
        Builds HTML for individual card item.
139
        
140
        Parameters:
141
        - parent: Parent XML element
142
        - item: Card item to render
143
        """
144
    
145
    def build_image_html(self, wrapper_element, item: CardItem) -> None:
146
        """
147
        Builds card image HTML.
148
        
149
        Parameters:
150
        - wrapper_element: Card wrapper element
151
        - item: Card item with image data
152
        """
153
```
154

155
## Usage Examples
156

157
### Basic Card Layout
158

159
Use `::cards::` blocks with embedded data:
160

161
```markdown
162
::cards::
163
- title: "Getting Started"
164
  content: "Learn the basics of using our platform"
165
  url: "/getting-started"
166
  icon: "play-circle"
167

168
- title: "API Reference"
169
  content: "Complete API documentation and examples"
170
  url: "/api"
171
  icon: "book"
172

173
- title: "Examples"
174
  content: "Code examples and tutorials"
175
  url: "/examples"
176
  icon: "code"
177
::end-cards::
178
```
179

180
### Cards with Images
181

182
```markdown
183
::cards::
184
- title: "Product A"
185
  content: "High-quality product with advanced features"
186
  url: "/products/a"
187
  image:
188
    url: "./images/product-a.jpg"
189
    alt: "Product A"
190

191
- title: "Product B"
192
  content: "Affordable solution for everyday use"
193
  url: "/products/b"
194
  image:
195
    url: "./images/product-b.jpg"
196
    alt: "Product B"
197
::end-cards::
198
```
199

200
### Custom Grid Layout
201

202
```markdown
203
::cards:: cols=4 class="feature-cards"
204
- title: "Fast"
205
  content: "Lightning-fast performance"
206
  icon: "zap"
207

208
- title: "Secure"
209
  content: "Enterprise-grade security"
210
  icon: "shield"
211

212
- title: "Scalable"
213
  content: "Grows with your business"
214
  icon: "trending-up"
215

216
- title: "Reliable"
217
  content: "99.9% uptime guarantee"
218
  icon: "check-circle"
219
::end-cards::
220
```
221

222
### Cards with Background Images
223

224
```markdown
225
::cards:: image_bg=true cols=2
226
- title: "Mountain Adventures"
227
  content: "Explore breathtaking mountain trails"
228
  image:
229
    url: "./images/mountains.jpg"
230
    alt: "Mountains"
231
  url: "/adventures/mountain"
232

233
- title: "Ocean Expeditions"
234
  content: "Discover underwater wonders"
235
  image:
236
    url: "./images/ocean.jpg"
237
    alt: "Ocean"
238
  url: "/adventures/ocean"
239
::end-cards::
240
```
241

242
### External Card Data
243

244
Reference external data sources:
245

246
```markdown
247
[cards(features.yaml)]
248
```
249

250
Where `features.yaml` contains:
251
```yaml
252
- title: "Feature One"
253
  content: "Description of feature one"
254
  icon: "star"
255
- title: "Feature Two"
256
  content: "Description of feature two"
257
  icon: "heart"
258
```
259

260
### Complex Card Example
261

262
```markdown
263
::cards:: id="product-showcase" cols=3 blank_target=true
264
- title: "Professional Plan"
265
  content: |
266
    Perfect for growing teams and businesses.
267
    
268
    Features:
269
    - Unlimited projects
270
    - Advanced analytics
271
    - Priority support
272
    - Custom integrations
273
  url: "/pricing/professional"
274
  icon: "briefcase"
275
  image:
276
    url: "./images/pro-plan.jpg"
277
    alt: "Professional Plan"
278
    width: 300
279
    height: 200
280

281
- title: "Enterprise Plan"
282
  content: |
283
    For large organizations with complex needs.
284
    
285
    Features:
286
    - Everything in Professional
287
    - Dedicated account manager
288
    - Custom SLA
289
    - On-premise deployment
290
  url: "/pricing/enterprise"
291
  icon: "building"
292
  image:
293
    url: "./images/enterprise-plan.jpg"
294
    alt: "Enterprise Plan"
295
    width: 300
296
    height: 200
297

298
- title: "Contact Sales"
299
  content: |
300
    Need a custom solution? Our sales team can help you find the perfect fit for your organization.
301
  url: "/contact"
302
  icon: "phone"
303
::end-cards::
304
```
305

306
## Data Source Support
307

308
### Supported Formats
309

310
The cards extension supports multiple data formats:
311

312
- **YAML**: Structured card data (recommended)
313
- **JSON**: JavaScript Object Notation format
314
- **CSV**: Comma-separated values with column headers
315

316
### External Data Sources
317

318
```markdown
319
<!-- Local files -->
320
[cards(./data/products.yaml)]
321
[cards(../shared/features.json)]
322

323
<!-- URLs (if configured) -->
324
[cards(https://api.example.com/cards.json)]
325
```
326

327
### CSV Format Example
328

329
```csv
330
title,content,url,icon
331
"Guide","User documentation","/docs","book"
332
"API","Technical reference","/api","code"
333
"Support","Get help","/support","help-circle"
334
```
335

336
### Image Data Formats
337

338
Images can be specified in multiple ways:
339

340
```yaml
341
# Simple string URL
342
- title: "Card with Image"
343
  image: "./images/card.jpg"
344

345
# Full image object
346
- title: "Card with Detailed Image"
347
  image:
348
    url: "./images/card.jpg"
349
    alt: "Card image description"
350
    width: 400
351
    height: 300
352

353
# Image with responsive attributes
354
- title: "Responsive Card"
355
  image:
356
    url: "./images/responsive-card.jpg"
357
    alt: "Responsive image"
358
```
359

360
## Styling and Customization
361

362
### CSS Classes
363

364
The cards extension generates semantic HTML with CSS classes:
365

366
```html
367
<div class="cards-container">
368
  <div class="card">
369
    <div class="card-image">
370
      <img src="..." alt="...">
371
    </div>
372
    <div class="card-content">
373
      <h3 class="card-title">Title</h3>
374
      <p class="card-description">Content</p>
375
    </div>
376
    <div class="card-icon">
377
      <i class="fas fa-icon"></i>
378
    </div>
379
  </div>
380
</div>
381
```
382

383
### Grid Layout Options
384

385
- `cols=1`: Single column layout
386
- `cols=2`: Two-column grid
387
- `cols=3`: Three-column grid (default)
388
- `cols=4`: Four-column grid
389
- `cols=6`: Six-column grid
390

391
### Link Behavior
392

393
- `blank_target=false`: Links open in same tab (default)
394
- `blank_target=true`: Links open in new tab/window
395

396
### Image Display Modes
397

398
- `image_bg=false`: Images display as standard img elements (default)
399
- `image_bg=true`: Images display as background images for full-card coverage