0
# Core Document Management
1

2
Central document creation, file operations, and basic content writing functionality. The MdUtils class serves as the main interface for creating and managing markdown documents, providing methods for initialization, file I/O, and fundamental text operations.
3

4
## Capabilities
5

6
### Document Initialization
7

8
Create new markdown documents with optional title, author, and styling preferences.
9

10
```python { .api }
11
class MdUtils:
12
    def __init__(self, file_name: str, title: str = "", author: str = "", title_header_style: str = "setext"):
13
        """
14
        Initialize a new markdown document.
15

16
        Parameters:
17
        - file_name (str): Name of the markdown file (without .md extension)
18
        - title (str, optional): Document title, rendered as H1 header
19
        - author (str, optional): Document author  
20
        - title_header_style (str): Header style for title ("setext" or "atx")
21
        """
22
```
23

24
**Usage Example:**
25

26
```python
27
from mdutils import MdUtils
28

29
# Basic document
30
md = MdUtils(file_name='basic_doc')
31

32
# Document with title and author
33
md = MdUtils(file_name='report', title='Monthly Report', author='John Doe')
34

35
# Document with ATX-style title
36
md = MdUtils(file_name='guide', title='User Guide', title_header_style='atx')
37
```
38

39
### File Operations
40

41
Create, write, and read markdown files with comprehensive file management capabilities.
42

43
```python { .api }
44
class MdUtils:
45
    def create_md_file(self) -> MarkDownFile:
46
        """
47
        Create and write the markdown file to disk.
48

49
        Returns:
50
        MarkDownFile: File object for further operations
51
        """
52

53
    def get_md_text(self) -> str:
54
        """
55
        Get the complete markdown content as a string without writing to file.
56

57
        Returns:
58
        str: Complete markdown document content
59
        """
60

61
    def read_md_file(self, file_name: str) -> str:
62
        """
63
        Read an existing markdown file and append its content to the current document.
64

65
        Parameters:
66
        - file_name (str): Path to the markdown file to read
67

68
        Returns:
69
        str: Content of the read file
70
        """
71
```
72

73
**Usage Example:**
74

75
```python
76
from mdutils import MdUtils
77

78
md = MdUtils(file_name='example')
79
md.new_paragraph('Hello World!')
80

81
# Write to file
82
md.create_md_file()  # Creates 'example.md'
83

84
# Get content as string
85
content = md.get_md_text()
86
print(content)
87

88
# Read existing file
89
md.read_md_file('existing_document.md')
90
```
91

92
### Basic Text Writing
93

94
Write text content with formatting options, positioning control, and text wrapping capabilities.
95

96
```python { .api }
97
class MdUtils:
98
    def write(self, text: str = "", bold_italics_code: str = "", color: str = "black", align: str = "", marker: str = "", wrap_width: int = 0) -> str:
99
        """
100
        Write formatted text to the document.
101

102
        Parameters:
103
        - text (str): Text content to write
104
        - bold_italics_code (str): Format codes ('b' for bold, 'i' for italics, 'c' for code)
105
        - color (str): Text color specification
106
        - align (str): Text alignment ('left', 'center', 'right')
107
        - marker (str): Marker for positioning text at specific location
108
        - wrap_width (int): Text wrapping width in characters (0 disables wrapping)
109

110
        Returns:
111
        str: Formatted text
112
        """
113

114
    def new_paragraph(self, text: str = "", bold_italics_code: str = "", color: str = "black", align: str = "", wrap_width: int = 0) -> str:
115
        """
116
        Add a new paragraph with double line breaks.
117

118
        Parameters:
119
        - text (str): Paragraph text content
120
        - bold_italics_code (str): Format codes ('b' for bold, 'i' for italics, 'c' for code)
121
        - color (str): Text color specification
122
        - align (str): Text alignment ('left', 'center', 'right')
123
        - wrap_width (int): Text wrapping width in characters
124

125
        Returns:
126
        str: Complete document content after adding paragraph
127
        """
128

129
    def new_line(self, text: str = "", bold_italics_code: str = "", color: str = "black", align: str = "", wrap_width: int = 0) -> str:
130
        """
131
        Add a new line with single line break.
132

133
        Parameters:
134
        - text (str): Line text content  
135
        - bold_italics_code (str): Format codes ('b' for bold, 'i' for italics, 'c' for code)
136
        - color (str): Text color specification
137
        - align (str): Text alignment ('left', 'center', 'right')
138
        - wrap_width (int): Text wrapping width in characters
139

140
        Returns:
141
        str: Complete document content after adding line
142
        """
143
```
144

145
**Usage Example:**
146

147
```python
148
from mdutils import MdUtils
149

150
md = MdUtils(file_name='content_example')
151

152
# Basic text writing
153
md.write('This is basic text.')
154

155
# New paragraph with formatting
156
md.new_paragraph('This is a **bold** paragraph.', bold_italics_code='b')
157

158
# New line with color and alignment
159
md.new_line('Centered red text', color='red', align='center')
160

161
# Text with wrapping
162
long_text = 'This is a very long line that will be wrapped at 50 characters width.'
163
md.new_paragraph(long_text, wrap_width=50)
164

165
# Write with marker for positioning
166
marker = md.create_marker('content_placeholder')
167
md.write('This text replaces the marker', marker=marker)
168
```
169

170
### Instance Attributes
171

172
Key attributes available on MdUtils instances for accessing document state and components.
173

174
```python { .api }
175
class MdUtils:
176
    file_name: str          # Document filename
177
    author: str             # Document author
178
    title: str              # Document title (rendered as header)
179
    table_of_contents: str  # Table of contents content
180
    file_data_text: str     # Main document content
181
    textUtils: TextUtils    # Text formatting utilities
182
    reference: Reference    # Reference link manager
183
    image: Image           # Image manager
184
```
185

186
**Usage Example:**
187

188
```python
189
from mdutils import MdUtils
190

191
md = MdUtils(file_name='document', title='My Document', author='Author Name')
192

193
# Access document properties
194
print(f"File: {md.file_name}")
195
print(f"Author: {md.author}")
196
print(f"Current content length: {len(md.file_data_text)}")
197

198
# Access utility components
199
bold_text = md.textUtils.bold('Important text')
200
md.write(bold_text)
201

202
# Check table of contents
203
if md.table_of_contents:
204
    print("Document has table of contents")
205
```
206

207
### Code Block Insertion
208

209
Insert syntax-highlighted code blocks with language specification for technical documentation.
210

211
```python { .api }
212
class MdUtils:
213
    def insert_code(self, code: str, language: str = "") -> str:
214
        """
215
        Insert a code block with optional syntax highlighting.
216

217
        Parameters:
218
        - code (str): Code content to insert
219
        - language (str, optional): Programming language for syntax highlighting
220

221
        Returns:
222
        str: Formatted code block
223
        """
224
```
225

226
**Usage Example:**
227

228
```python
229
from mdutils import MdUtils
230

231
md = MdUtils(file_name='code_example')
232

233
# Python code block
234
python_code = '''
235
def hello_world():
236
    print("Hello, World!")
237
    return True
238
'''
239
md.insert_code(python_code, language='python')
240

241
# JavaScript code block
242
js_code = '''
243
function greet(name) {
244
    console.log(`Hello, ${name}!`);
245
}
246
'''
247
md.insert_code(js_code, language='javascript')
248

249
# Code without language specification
250
md.insert_code('echo "Hello World"')
251
```