0
# MDUtils
1

2
A comprehensive Python library for programmatically creating and manipulating Markdown files during code execution. MDUtils provides a complete set of tools for generating well-formatted Markdown documents with support for headers, tables, lists, images, links, text formatting, and advanced features like table of contents generation and content positioning.
3

4
## Package Information
5

6
- **Package Name**: mdutils
7
- **Language**: Python
8
- **Installation**: `pip install mdutils`
9
- **Repository**: https://github.com/didix21/mdutils
10
- **Documentation**: http://mdutils.readthedocs.io
11

12
## Core Imports
13

14
```python
15
from mdutils import MdUtils
16
```
17

18
Import specific components:
19

20
```python  
21
from mdutils import MdUtils, Header, Link, Image, TextUtils, Table, TableOfContents, Html, MDList
22
# Note: MDCheckbox must be imported from tools
23
from mdutils.tools import MDCheckbox
24
```
25

26
Import utilities directly:
27

28
```python
29
from mdutils.fileutils import fileutils
30
# Or import directly:
31
from mdutils.fileutils.fileutils import MarkDownFile
32
from mdutils.tools import Header, Link, Image, TextUtils, Table, TableOfContents, Html, MDList, MDCheckbox
33
```
34

35
## Basic Usage
36

37
```python
38
from mdutils import MdUtils
39

40
# Create a new markdown document
41
mdFile = MdUtils(file_name='Example', title='My Document', author='Your Name')
42

43
# Add content
44
mdFile.new_header(level=1, title='Introduction')
45
mdFile.new_paragraph('This is a paragraph with **bold** text.')
46

47
# Add a simple table
48
table_data = ['Header 1', 'Header 2', 'Row 1 Col 1', 'Row 1 Col 2', 'Row 2 Col 1', 'Row 2 Col 2']
49
mdFile.new_table(columns=2, rows=3, text=table_data, text_align='center')
50

51
# Add a list
52
items = ['First item', 'Second item', 'Third item']
53
mdFile.new_list(items)
54

55
# Generate the markdown file
56
mdFile.create_md_file()
57

58
# Or get the content as a string
59
content = mdFile.get_md_text()
60
print(content)
61
```
62

63
## Architecture
64

65
MDUtils follows a modular architecture with specialized tool classes:
66

67
- **MdUtils**: Main document class that orchestrates content creation and file operations
68
- **Tool Classes**: Specialized utilities for specific markdown elements (Header, Table, Link, Image, etc.)
69
- **FileUtils**: File I/O operations for reading, writing, and appending markdown files
70
- **Reference System**: Manages reference-style links and images with automatic reference generation
71

72
The design enables both simple, direct usage through the main MdUtils class and advanced customization through direct tool access.
73

74
## Capabilities
75

76
### Core Document Management
77

78
Central document creation, file operations, and basic content writing functionality including initialization, file I/O, and fundamental text operations.
79

80
```python { .api }
81
class MdUtils:
82
    def __init__(self, file_name: str, title: str = "", author: str = "", title_header_style: str = "setext"): ...
83
    def create_md_file(self) -> MarkDownFile: ...
84
    def get_md_text(self) -> str: ...
85
    def read_md_file(self, file_name: str) -> str: ...
86
    def write(self, text: str = "", bold_italics_code: str = "", color: str = "black", align: str = "", marker: str = "", wrap_width: int = 0) -> str: ...
87
    def new_paragraph(self, text: str = "", bold_italics_code: str = "", color: str = "black", align: str = "", wrap_width: int = 0) -> str: ...
88
    def new_line(self, text: str = "", bold_italics_code: str = "", color: str = "black", align: str = "", wrap_width: int = 0) -> str: ...
89
```
90

91
[Core Document Management](./core-document.md)
92

93
### Text Formatting
94

95
Comprehensive text styling capabilities including bold, italics, colors, alignment, inline code, and advanced formatting combinations.
96

97
```python { .api }
98
class TextUtils:
99
    @staticmethod
100
    def bold(text: str) -> str: ...
101
    @staticmethod
102
    def italics(text: str) -> str: ...
103
    @staticmethod
104
    def inline_code(text: str) -> str: ...
105
    @staticmethod
106
    def text_color(text: str, color: str = "black") -> str: ...
107
    @staticmethod
108
    def center_text(text: str) -> str: ...
109
    @staticmethod
110
    def text_format(text: str, bold_italics_code: str = "", color: str = "black", align: str = "") -> str: ...
111
```
112

113
[Text Formatting](./text-formatting.md)
114

115
### Headers and Table of Contents
116

117
Header creation with multiple styles and automated table of contents generation with customizable depth and positioning.
118

119
```python { .api }
120
class MdUtils:
121
    def new_header(self, level: int, title: str, style: str = "atx", add_table_of_contents: str = "y", header_id: str = "") -> str: ...
122
    def new_table_of_contents(self, table_title: str = "Table of contents", depth: int = 1, marker: str = "") -> str: ...
123

124
class Header:
125
    def __init__(self, level: int, title: str, style: HeaderStyle, header_id: str = None): ...
126
    @staticmethod
127
    def atx(level: AtxHeaderLevel, title: str, header_id: str = None) -> str: ...
128
    @staticmethod
129
    def setext(level: SetextHeaderLevel, title: str) -> str: ...
130
```
131

132
[Headers and Table of Contents](./headers-toc.md)
133

134
### Tables
135

136
Flexible table creation from flat lists or 2D arrays with customizable alignment, supporting various data input formats and styling options.
137

138
```python { .api }
139
class MdUtils:
140
    def new_table(self, columns: int, rows: int, text: List[str], text_align: Optional[Union[str, list]] = "center", marker: str = "") -> str: ...
141
    def new_table_array(self, data: List[List[str]], text_align: Optional[Union[str, list]] = None, marker: str = "") -> str: ...
142

143
class Table:
144
    def create_table(self, columns: int, rows: int, text: List[str], text_align: Optional[Union[str, list]] = None) -> str: ...
145
    def create_table_array(self, data: List[List[str]], text_align: Optional[Union[str, list]] = None) -> str: ...
146
```
147

148
[Tables](./tables.md)
149

150
### Lists
151

152
Creation of ordered lists, unordered lists, and interactive checkbox lists with support for custom markers and nested structures.
153

154
```python { .api }
155
class MdUtils:
156
    def new_list(self, items: List[str], marked_with: str = "-"): ...
157
    def new_checkbox_list(self, items: List[str], checked: bool = False): ...
158

159
class MDList:
160
    def __init__(self, items, marked_with: str = "-"): ...
161
    def get_md(self) -> str: ...
162

163
class MDCheckbox:
164
    def __init__(self, items, checked: bool = False): ...
165
    def get_md(self) -> str: ...
166
```
167

168
[Lists](./lists.md)
169

170
### Links and Images
171

172
Comprehensive link and image support including inline and reference styles, with automatic reference management and tooltip support.
173

174
```python { .api }
175
class MdUtils:
176
    def new_inline_link(self, link: str, text: Optional[str] = None, bold_italics_code: str = "", align: str = "") -> str: ...
177
    def new_reference_link(self, link: str, text: str, reference_tag: Optional[str] = None, bold_italics_code: str = "", align: str = "") -> str: ...
178
    @staticmethod
179
    def new_inline_image(text: str, path: str) -> str: ...
180
    def new_reference_image(self, text: str, path: str, reference_tag: Optional[str] = None) -> str: ...
181

182
class Inline:
183
    @staticmethod
184
    def new_link(link: str, text: str = None, tooltip: str = None): ...
185

186
class Image:
187
    @staticmethod
188
    def new_inline_image(text: str, path: str, tooltip: str = None) -> str: ...
189
    def new_reference_image(self, text: str, path: str, reference_tag: str = None, tooltip: str = None) -> str: ...
190
```
191

192
[Links and Images](./links-images.md)
193

194
### Advanced Features
195

196
Advanced functionality including content markers for precise positioning, HTML integration, code block insertion, and file utilities for complex document operations.
197

198
```python { .api }
199
class MdUtils:
200
    def create_marker(self, text_marker: str) -> str: ...
201
    def place_text_using_marker(self, text: str, marker: str) -> str: ...
202
    def insert_code(self, code: str, language: str = "") -> str: ...
203

204
class Html:
205
    @staticmethod
206
    def paragraph(text: str, align: str = None) -> str: ...
207
    @classmethod
208
    def image(cls, path: str, size: str = None, align: str = None) -> str: ...
209

210
class MarkDownFile:
211
    def __init__(self, name="", dirname: Optional[str] = None): ...
212
    def rewrite_all_file(self, data: str): ...
213
    def append_end(self, data: str): ...
214
    @staticmethod
215
    def read_file(file_name: str) -> str: ...
216
```
217

218
[Advanced Features](./advanced.md)
219

220
## Types
221

222
```python { .api }
223
# Enums for header styling
224
class HeaderStyle(Enum):
225
    ATX = "atx"
226
    SETEXT = "setext"
227

228
class AtxHeaderLevel(Enum):
229
    TITLE = 1        # H1
230
    HEADING = 2      # H2  
231
    SUBHEADING = 3   # H3
232
    SUBSUBHEADING = 4 # H4
233
    MINORHEADING = 5  # H5
234
    LEASTHEADING = 6  # H6
235

236
class SetextHeaderLevel(Enum):
237
    TITLE = 1    # H1
238
    HEADING = 2  # H2
239

240
# Exception types
241
class SizeBadFormat(Exception):
242
    def __init__(self, message): ...
243
```