0
# Lists
1

2
Creation of ordered lists, unordered lists, and interactive checkbox lists with support for custom markers and nested structures. MDUtils provides comprehensive list creation capabilities for organizing content with various list types and formatting options.
3

4
## Capabilities
5

6
### Basic List Creation
7

8
Create unordered and ordered lists with customizable markers and content.
9

10
```python { .api }
11
class MdUtils:
12
    def new_list(self, items: List[str], marked_with: str = "-"):
13
        """
14
        Create unordered or ordered lists in the markdown document.
15

16
        Parameters:
17
        - items (List[str]): Array of list items
18
        - marked_with (str): List marker:
19
          - '-', '+', '*' for unordered lists
20
          - '1' for ordered (numbered) lists
21

22
        Returns:
23
        None (content added to document)
24
        """
25
```
26

27
**Usage Example:**
28

29
```python
30
from mdutils import MdUtils
31

32
md = MdUtils(file_name='basic_lists')
33

34
# Unordered list with default marker (-)
35
shopping_list = ['Milk', 'Bread', 'Eggs', 'Butter']
36
md.new_header(level=2, title='Shopping List')
37
md.new_list(items=shopping_list)
38

39
# Unordered list with different markers
40
md.new_header(level=2, title='Features (+ marker)')
41
features = ['Easy to use', 'Fast performance', 'Cross-platform']
42
md.new_list(items=features, marked_with='+')
43

44
md.new_header(level=2, title='Benefits (* marker)')
45
benefits = ['Cost effective', 'Time saving', 'Reliable']
46
md.new_list(items=benefits, marked_with='*')
47

48
# Ordered (numbered) list
49
md.new_header(level=2, title='Installation Steps')
50
steps = [
51
    'Download the package',
52
    'Extract the files', 
53
    'Run the installer',
54
    'Configure settings',
55
    'Start the application'
56
]
57
md.new_list(items=steps, marked_with='1')
58
```
59

60
### Checkbox Lists
61

62
Create interactive checkbox lists for task tracking and completion status.
63

64
```python { .api }
65
class MdUtils:
66
    def new_checkbox_list(self, items: List[str], checked: bool = False):
67
        """
68
        Create checkbox lists for task tracking.
69

70
        Parameters:
71
        - items (List[str]): Array of checkbox items
72
        - checked (bool): Default state for all checkboxes (True=checked, False=unchecked)
73

74
        Returns:
75
        None (content added to document)
76
        """
77
```
78

79
**Usage Example:**
80

81
```python
82
from mdutils import MdUtils
83

84
md = MdUtils(file_name='checkbox_lists')
85

86
# Unchecked task list (default)
87
md.new_header(level=2, title='Project Tasks')
88
tasks = [
89
    'Design user interface',
90
    'Implement authentication',
91
    'Set up database',
92
    'Write unit tests',
93
    'Deploy to production'
94
]
95
md.new_checkbox_list(items=tasks)
96

97
# Pre-checked completion list
98
md.new_header(level=2, title='Completed Items')
99
completed_items = [
100
    'Initial planning',
101
    'Team assignment', 
102
    'Resource allocation'
103
]
104
md.new_checkbox_list(items=completed_items, checked=True)
105

106
# Mixed status checklist (requires manual creation)
107
md.new_header(level=2, title='Review Checklist')
108
md.write('- [x] Code review completed')
109
md.new_line('- [x] Documentation updated')
110
md.new_line('- [ ] Performance testing')
111
md.new_line('- [ ] Security audit')
112
```
113

114
### List Tool Classes
115

116
Direct access to list creation tools for advanced list manipulation and custom formatting.
117

118
```python { .api }
119
class MDList:
120
    def __init__(self, items, marked_with: str = "-"):
121
        """
122
        Initialize a markdown list generator.
123

124
        Parameters:
125
        - items: List items (can be nested)
126
        - marked_with (str): List marker ('-', '+', '*', '1')
127
        """
128

129
    def get_md(self) -> str:
130
        """
131
        Get the formatted markdown list.
132

133
        Returns:
134
        str: Complete markdown list string
135
        """
136

137
    # Properties
138
    n_tabs: int    # Number of tab levels for nesting
139
    md_list: str   # The generated markdown list content
140

141
class MDCheckbox:
142
    def __init__(self, items, checked: bool = False):
143
        """
144
        Initialize a markdown checkbox list generator.
145

146
        Parameters:
147
        - items: List items for checkboxes
148
        - checked (bool): Default checked state
149
        """
150

151
    def get_md(self) -> str:
152
        """
153
        Get the formatted markdown checkbox list.
154

155
        Returns:
156
        str: Complete markdown checkbox list string
157
        """
158

159
    # Properties
160
    n_tabs: int     # Number of tab levels for nesting
161
    md_list: str    # The generated markdown list content
162
    checked: str    # Checkbox state marker
163
```
164

165
**Usage Example:**
166

167
```python
168
from mdutils import MdUtils
169
from mdutils.tools import MDList, MDCheckbox
170

171
md = MdUtils(file_name='list_tools_example')
172

173
# Using MDList class directly
174
items = ['First item', 'Second item', 'Third item']
175
list_generator = MDList(items, marked_with='+')
176
list_content = list_generator.get_md()
177
md.write(list_content)
178

179
# Using MDCheckbox class directly
180
checkbox_items = ['Task A', 'Task B', 'Task C']
181
checkbox_generator = MDCheckbox(checkbox_items, checked=False)
182
checkbox_content = checkbox_generator.get_md()
183
md.write(checkbox_content)
184

185
# Access properties
186
print(f"List tabs: {list_generator.n_tabs}")
187
print(f"Checkbox state: {checkbox_generator.checked}")
188
```
189

190
### Advanced List Patterns
191

192
Complex list structures including nested lists and mixed content types.
193

194
**Nested Lists (Manual Creation):**
195

196
```python
197
from mdutils import MdUtils
198

199
md = MdUtils(file_name='nested_lists')
200

201
md.new_header(level=2, title='Project Structure')
202

203
# Create nested list manually using write methods
204
md.write('- Frontend')
205
md.new_line('  - React Components')
206
md.new_line('    - Header Component')  
207
md.new_line('    - Navigation Component')
208
md.new_line('    - Content Component')
209
md.new_line('  - Styling')
210
md.new_line('    - CSS Modules')
211
md.new_line('    - Theme System')
212

213
md.new_line('- Backend')
214
md.new_line('  - API Routes')
215
md.new_line('    - Authentication')
216
md.new_line('    - User Management')
217
md.new_line('    - Data Operations')
218
md.new_line('  - Database')
219
md.new_line('    - Schema Design')
220
md.new_line('    - Migrations')
221

222
md.new_line('- Testing')
223
md.new_line('  - Unit Tests')
224
md.new_line('  - Integration Tests')
225
md.new_line('  - End-to-End Tests')
226
```
227

228
### List Marker Reference
229

230
Complete guide to available list markers and their usage patterns.
231

232
**Unordered List Markers:**
233
- `-` (hyphen) - Default, widely supported
234
- `+` (plus) - Alternative marker
235
- `*` (asterisk) - Alternative marker
236

237
**Ordered List Markers:**
238
- `1` - Creates numbered lists (1., 2., 3., ...)
239

240
**Checkbox Markers:**
241
- `[ ]` - Unchecked checkbox
242
- `[x]` - Checked checkbox
243

244
**Usage Example:**
245

246
```python
247
from mdutils import MdUtils
248

249
md = MdUtils(file_name='marker_reference')
250

251
# All unordered marker types
252
md.new_header(level=2, title='Unordered List Markers')
253

254
md.new_header(level=3, title='Hyphen Marker (-)')
255
hyphen_items = ['Item 1', 'Item 2', 'Item 3']
256
md.new_list(items=hyphen_items, marked_with='-')
257

258
md.new_header(level=3, title='Plus Marker (+)')
259
plus_items = ['Feature A', 'Feature B', 'Feature C']
260
md.new_list(items=plus_items, marked_with='+')
261

262
md.new_header(level=3, title='Asterisk Marker (*)')
263
asterisk_items = ['Point 1', 'Point 2', 'Point 3']
264
md.new_list(items=asterisk_items, marked_with='*')
265

266
# Ordered list
267
md.new_header(level=3, title='Numbered List (1)')
268
numbered_items = ['First step', 'Second step', 'Third step']
269
md.new_list(items=numbered_items, marked_with='1')
270

271
# Checkbox examples
272
md.new_header(level=3, title='Checkbox Lists')
273
unchecked_tasks = ['Pending task 1', 'Pending task 2']
274
md.new_checkbox_list(items=unchecked_tasks, checked=False)
275

276
checked_tasks = ['Completed task 1', 'Completed task 2']
277
md.new_checkbox_list(items=checked_tasks, checked=True)
278
```
279

280
### Practical List Examples
281

282
Real-world examples demonstrating effective list usage patterns.
283

284
**Usage Example:**
285

286
```python
287
from mdutils import MdUtils
288

289
md = MdUtils(file_name='practical_lists')
290

291
# Meeting agenda
292
md.new_header(level=1, title='Weekly Team Meeting')
293
md.new_header(level=2, title='Agenda')
294
agenda_items = [
295
    'Review previous week\'s progress',
296
    'Discuss current sprint goals',
297
    'Address any blockers or issues',
298
    'Plan for upcoming tasks',
299
    'Team announcements'
300
]
301
md.new_list(items=agenda_items, marked_with='1')
302

303
# Action items checklist
304
md.new_header(level=2, title='Action Items')
305
action_items = [
306
    'Update project documentation',
307
    'Schedule client review meeting',
308
    'Prepare deployment checklist',
309
    'Review security audit results',
310
    'Update team on budget status'
311
]
312
md.new_checkbox_list(items=action_items)
313

314
# Feature comparison
315
md.new_header(level=2, title='Product Features')
316

317
md.new_header(level=3, title='Basic Plan')
318
basic_features = [
319
    'Up to 5 users',
320
    'Basic reporting',
321
    'Email support',
322
    '10GB storage'
323
]
324
md.new_list(items=basic_features, marked_with='+')
325

326
md.new_header(level=3, title='Premium Plan')
327
premium_features = [
328
    'Unlimited users',
329
    'Advanced analytics',
330
    'Priority support',
331
    '100GB storage',
332
    'API access',
333
    'Custom integrations'
334
]
335
md.new_list(items=premium_features, marked_with='+')
336

337
# Process workflow
338
md.new_header(level=2, title='Development Workflow')
339
workflow_steps = [
340
    'Create feature branch from main',
341
    'Implement feature with unit tests',
342
    'Submit pull request for review',
343
    'Address review feedback',
344
    'Merge to main branch',
345
    'Deploy to staging environment',
346
    'Perform QA testing',
347
    'Deploy to production'
348
]
349
md.new_list(items=workflow_steps, marked_with='1')
350

351
# Progress tracking
352
md.new_header(level=2, title='Release 2.0 Progress')
353
release_tasks = [
354
    'User authentication system',
355
    'Database schema updates',
356
    'Frontend redesign',
357
    'API documentation',
358
    'Performance optimizations',
359
    'Security enhancements'
360
]
361
md.new_checkbox_list(items=release_tasks, checked=False)
362

363
# Completed milestones
364
md.new_header(level=2, title='Completed Milestones')
365
completed_milestones = [
366
    'Project planning phase',
367
    'Initial architecture design',
368
    'Development environment setup',
369
    'Core framework implementation'
370
]
371
md.new_checkbox_list(items=completed_milestones, checked=True)
372
```