0
# Content Structure Extensions
1

2
Extensions for organizing and structuring content including task lists with checkboxes, tabbed interfaces, collapsible details sections, visual progress bars, and enhanced list formatting.
3

4
## Capabilities
5

6
### Task Lists
7

8
GitHub-style task lists with interactive checkboxes, supporting both completed and pending tasks with customizable styling.
9

10
```python { .api }
11
def makeExtension(**kwargs):
12
    """
13
    Create TaskList extension for GitHub-style task lists.
14
    
15
    Configuration:
16
    - custom_checkbox: bool - Use custom checkbox HTML (False)
17
    - clickable_checkbox: bool - Make checkboxes clickable (False)
18
    - checkbox_text: str - Custom checkbox HTML text
19
    
20
    Returns:
21
    TasklistExtension instance
22
    """
23

24
class TasklistExtension(Extension):
25
    """GitHub-style task list extension."""
26

27
class TasklistTreeprocessor(Treeprocessor):
28
    """Task list processing and checkbox generation."""
29

30
def get_checkbox(checked=False, clickable=False):
31
    """
32
    Generate checkbox HTML for task lists.
33
    
34
    Parameters:
35
    - checked: bool - Whether checkbox is checked
36
    - clickable: bool - Whether checkbox is interactive
37
    
38
    Returns:
39
    str - Checkbox HTML
40
    """
41
```
42

43
**Usage Example:**
44

45
```python
46
import markdown
47

48
md = markdown.Markdown(extensions=['pymdownx.tasklist'])
49

50
text = """
51
## Todo List
52

53
- [x] Completed task
54
- [ ] Pending task
55
- [x] Another completed task
56
  - [ ] Nested pending task
57
  - [x] Nested completed task
58
"""
59
html = md.convert(text)
60
```
61

62
### Tabbed Content
63

64
Create tabbed interfaces and content blocks with support for nested tabs and customizable styling.
65

66
```python { .api }
67
def makeExtension(**kwargs):
68
    """
69
    Create Tabbed extension for tabbed content interfaces.
70
    
71
    Configuration:
72
    - alternate_style: bool - Use alternate tab styling (False)
73
    - combine_header_slug: bool - Combine header with slug (False)
74
    - slugify: callable - Custom slugify function
75
    
76
    Returns:
77
    TabbedExtension instance
78
    """
79

80
class TabbedExtension(Extension):
81
    """Tabbed content extension."""
82

83
class TabbedProcessor(BlockProcessor):
84
    """Tabbed content processor."""
85
```
86

87
**Usage Example:**
88

89
```python
90
import markdown
91

92
md = markdown.Markdown(extensions=['pymdownx.tabbed'])
93

94
text = """
95
=== "Tab 1"
96

97
    Content for tab 1
98

99
=== "Tab 2"
100

101
    Content for tab 2
102

103
=== "Tab 3"
104

105
    Content for tab 3
106
"""
107
html = md.convert(text)
108
```
109

110
### Details (Collapsible Sections)
111

112
HTML details/summary collapsible blocks for creating expandable content sections.
113

114
```python { .api }
115
def makeExtension(**kwargs):
116
    """
117
    Create Details extension for collapsible content blocks.
118
    
119
    Configuration:
120
    - open_details: bool - Open details by default (False)
121
    
122
    Returns:
123
    DetailsExtension instance
124
    """
125

126
class DetailsExtension(Extension):
127
    """Details/summary collapsible blocks extension."""
128

129
class DetailsProcessor(BlockProcessor):
130
    """Details block processor."""
131
```
132

133
**Usage Example:**
134

135
```python
136
import markdown
137

138
md = markdown.Markdown(extensions=['pymdownx.details'])
139

140
text = """
141
??? "Click to expand"
142

143
    This content is initially hidden and can be expanded by clicking the summary.
144

145
??? note "Important Note"
146

147
    This is an important note that starts collapsed.
148

149
???+ warning "Always Visible"
150

151
    This details block starts expanded (+ modifier).
152
"""
153
html = md.convert(text)
154
```
155

156
### Progress Bar
157

158
Visual progress bars with percentage indicators and customizable styling for showing completion status.
159

160
```python { .api }
161
def makeExtension(**kwargs):
162
    """
163
    Create ProgressBar extension for visual progress indicators.
164
    
165
    Configuration:
166
    - progress_increment: int - Progress bar increment value (5)
167
    - add_classes: str - Additional CSS classes
168
    - level_class: bool - Include class that defines progress level (True)
169
    
170
    Returns:
171
    ProgressBarExtension instance
172
    """
173

174
class ProgressBarExtension(Extension):
175
    """Progress bar extension."""
176

177
class ProgressBarPattern(InlineProcessor):
178
    """Progress bar pattern processor."""
179

180
class ProgressBarTreeProcessor(AttrListTreeprocessor):
181
    """Progress bar tree processor."""
182
```
183

184
**Usage Example:**
185

186
```python
187
import markdown
188

189
md = markdown.Markdown(extensions=['pymdownx.progressbar'])
190

191
text = """
192
Progress: [=75%] (75%)
193

194
Loading: [===60%] (60%)
195

196
Complete: [=100%] (100%)
197
"""
198
html = md.convert(text)
199
```
200

201
### Fancy Lists
202

203
Enhanced ordered lists with custom numbering styles including Roman numerals, letters, and custom start values.
204

205
```python { .api }
206
def makeExtension(**kwargs):
207
    """
208
    Create FancyLists extension for enhanced ordered lists.
209
    
210
    Configuration:
211
    - generic: bool - Generic list attribute support (True)
212
    
213
    Returns:
214
    FancyListsExtension instance
215
    """
216

217
class FancyListsExtension(Extension):
218
    """Enhanced ordered lists extension."""
219

220
class FancyListsTreeprocessor(Treeprocessor):
221
    """List processing with custom numbering support."""
222
```
223

224
**Usage Example:**
225

226
```python
227
import markdown
228

229
md = markdown.Markdown(extensions=['pymdownx.fancylists'])
230

231
text = """
232
1) First item (parenthesis style)
233
2) Second item
234
3) Third item
235

236
a. Letter numbering
237
b. Second letter
238
c. Third letter
239

240
i. Roman numerals
241
ii. Second roman
242
iii. Third roman
243
"""
244
html = md.convert(text)
245
```
246

247
### Sane Headers
248

249
Improved header parsing and validation with better handling of header syntax and structure.
250

251
```python { .api }
252
def makeExtension(**kwargs):
253
    """
254
    Create SaneHeaders extension for improved header processing.
255
    
256
    Returns:
257
    SaneHeadersExtension instance
258
    """
259

260
class SaneHeadersExtension(Extension):
261
    """Sane header processing extension."""
262

263
class SaneHeadersProcessor(HashHeaderProcessor):
264
    """Header processor with improved validation."""
265
```
266

267
**Usage Example:**
268

269
```python
270
import markdown
271

272
md = markdown.Markdown(extensions=['pymdownx.saneheaders'])
273

274
# Better handling of edge cases in header syntax
275
text = """
276
# Valid Header
277

278
## Another Valid Header
279

280
### Third Level Header
281
"""
282
html = md.convert(text)
283
```
284

285
## Advanced Content Structure Patterns
286

287
### Nested Tabbed Content
288

289
```python
290
text = """
291
=== "Outer Tab 1"
292

293
    === "Inner Tab A"
294
    
295
        Content for inner tab A
296
    
297
    === "Inner Tab B"
298
    
299
        Content for inner tab B
300

301
=== "Outer Tab 2"
302

303
    Regular content without inner tabs
304
"""
305
```
306

307
### Combined Task Lists and Details
308

309
```python
310
text = """
311
??? "Project Tasks"
312

313
    - [x] Design phase complete
314
    - [x] Development started
315
    - [ ] Testing phase
316
      - [x] Unit tests
317
      - [ ] Integration tests
318
      - [ ] User acceptance testing
319
    - [ ] Deployment
320
"""
321
```
322

323
### Progress Tracking with Custom Styling
324

325
```python
326
extension_configs = {
327
    'pymdownx.progressbar': {
328
        'add_classes': 'custom-progress',
329
        'progress_increment': 10
330
    }
331
}
332

333
text = """
334
Project Completion: [===30%]{: .project-progress} (30%)
335

336
Feature Development: [=======70%]{: .feature-progress} (70%)
337
"""
338
```
339

340
### Advanced List Formatting
341

342
```python
343
text = """
344
{: type="I" start="5"}
345
5. Fifth item in Roman numerals
346
6. Sixth item
347
7. Seventh item
348

349
{: type="a"}
350
1. First letter item  
351
2. Second letter item
352
3. Third letter item
353
"""
354
```
355

356
## Configuration Examples
357

358
### Task List Customization
359

360
```python
361
extension_configs = {
362
    'pymdownx.tasklist': {
363
        'custom_checkbox': True,
364
        'clickable_checkbox': True,
365
        'checkbox_text': '<input type="checkbox" %s>'
366
    }
367
}
368
```
369

370
### Tabbed Content Styling
371

372
```python
373
extension_configs = {
374
    'pymdownx.tabbed': {
375
        'alternate_style': True,
376
        'combine_header_slug': True
377
    }
378
}
379
```
380

381
### Details Block Configuration
382

383
```python
384
extension_configs = {
385
    'pymdownx.details': {
386
        'open_details': True  # Start with details expanded
387
    }
388
}
389
```
390

391
## Types
392

393
```python { .api }
394
from typing import Callable, Optional, Union
395
from markdown import Extension, BlockProcessor, Treeprocessor, InlineProcessor
396

397
# Custom function types
398
SlugifyFunc = Callable[[str, str], str]  # Custom slugify function
399
CheckboxGenerator = Callable[[bool, bool], str]  # Checkbox HTML generator
400

401
# Configuration types
402
ProgressIncrement = int  # Progress bar increment value
403
ListType = str  # List numbering type ('1', 'a', 'A', 'i', 'I')
404
ListStart = int  # List start number
405
```