0
# Links and Images
1
2
Comprehensive link and image support including inline and reference styles, with automatic reference management and tooltip support. MDUtils provides flexible options for incorporating links and images into markdown documents with various formatting and positioning capabilities.
3
4
## Capabilities
5
6
### Inline Links
7
8
Create direct inline links with optional text formatting and styling.
9
10
```python { .api }
11
class MdUtils:
12
def new_inline_link(self, link: str, text: Optional[str] = None, bold_italics_code: str = "", align: str = "") -> str:
13
"""
14
Create inline markdown links.
15
16
Parameters:
17
- link (str): URL or link destination
18
- text (str, optional): Display text (defaults to link if not provided)
19
- bold_italics_code (str): Format codes ('b', 'i', 'c' and combinations)
20
- align (str): Text alignment ('left', 'center', 'right')
21
22
Returns:
23
str: Formatted inline link
24
"""
25
26
class Inline:
27
@staticmethod
28
def new_link(link: str, text: str = None, tooltip: str = None):
29
"""
30
Create inline links with optional tooltips.
31
32
Parameters:
33
- link (str): URL or link destination
34
- text (str, optional): Display text
35
- tooltip (str, optional): Tooltip text on hover
36
37
Returns:
38
str: Formatted inline link
39
"""
40
```
41
42
**Usage Example:**
43
44
```python
45
from mdutils import MdUtils
46
from mdutils.tools import Inline
47
48
md = MdUtils(file_name='inline_links_example')
49
50
# Basic inline links
51
md.new_paragraph('Visit our website at https://example.com')
52
53
# Inline link with custom text
54
github_link = md.new_inline_link('https://github.com/didix21/mdutils', 'MDUtils Repository')
55
md.new_paragraph(f'Check out the {github_link} for more information.')
56
57
# Formatted inline links
58
bold_link = md.new_inline_link('https://docs.python.org', 'Python Documentation', bold_italics_code='b')
59
italic_link = md.new_inline_link('https://markdown.org', 'Markdown Guide', bold_italics_code='i')
60
code_link = md.new_inline_link('https://github.com', 'GitHub', bold_italics_code='c')
61
62
md.new_paragraph(f'Resources: {bold_link}, {italic_link}, {code_link}')
63
64
# Using Inline class directly with tooltips
65
tooltip_link = Inline.new_link('https://example.com', 'Example Site', 'Click to visit example')
66
md.new_paragraph(f'Link with tooltip: {tooltip_link}')
67
68
# Links with alignment
69
centered_link = md.new_inline_link('https://centered-site.com', 'Centered Link', align='center')
70
md.write(centered_link)
71
```
72
73
### Reference Links
74
75
Create reference-style links with automatic reference management and formatting options.
76
77
```python { .api }
78
class MdUtils:
79
def new_reference_link(self, link: str, text: str, reference_tag: Optional[str] = None, bold_italics_code: str = "", align: str = "") -> str:
80
"""
81
Create reference-style links with automatic reference collection.
82
83
Parameters:
84
- link (str): URL or link destination
85
- text (str): Display text for the link
86
- reference_tag (str, optional): Custom reference tag (defaults to text)
87
- bold_italics_code (str): Format codes for text styling
88
- align (str): Text alignment
89
90
Returns:
91
str: Reference link marker (actual link stored for document end)
92
"""
93
94
class Reference:
95
def __init__(self):
96
"""Initialize reference link manager."""
97
98
def new_link(self, link: str, text: str, reference_tag: str = None, tooltip: str = None) -> str:
99
"""
100
Create reference-style links with tooltip support.
101
102
Parameters:
103
- link (str): URL or link destination
104
- text (str): Display text
105
- reference_tag (str, optional): Custom reference identifier
106
- tooltip (str, optional): Tooltip text
107
108
Returns:
109
str: Reference link marker
110
"""
111
112
def get_references(self) -> dict:
113
"""
114
Get all stored reference links.
115
116
Returns:
117
dict: Dictionary of all reference links
118
"""
119
120
def get_references_as_markdown(self) -> str:
121
"""
122
Get all references formatted as markdown for document end.
123
124
Returns:
125
str: Formatted reference section
126
"""
127
```
128
129
**Usage Example:**
130
131
```python
132
from mdutils import MdUtils
133
134
md = MdUtils(file_name='reference_links_example')
135
136
# Basic reference links
137
md.new_header(level=1, title='Documentation Links')
138
139
# Reference link with default tag
140
python_ref = md.new_reference_link('https://docs.python.org', 'Python Documentation')
141
md.new_paragraph(f'For Python help, see {python_ref}.')
142
143
# Reference link with custom tag
144
github_ref = md.new_reference_link('https://github.com/didix21/mdutils', 'MDUtils', 'mdutils-repo')
145
md.new_paragraph(f'The source code is available at {github_ref}.')
146
147
# Formatted reference links
148
bold_ref = md.new_reference_link('https://important-site.com', 'Important Resource', 'important', bold_italics_code='b')
149
md.new_paragraph(f'Please review this {bold_ref} before proceeding.')
150
151
# Multiple references to same link with different tags
152
stackoverflow_ref1 = md.new_reference_link('https://stackoverflow.com', 'StackOverflow', 'so-general')
153
stackoverflow_ref2 = md.new_reference_link('https://stackoverflow.com', 'SO', 'so-short')
154
155
md.new_paragraph(f'Get help at {stackoverflow_ref1} or {stackoverflow_ref2}.')
156
157
# Access reference manager directly
158
print("Current references:", md.reference.get_references())
159
160
# References will be automatically added to document end when creating file
161
md.create_md_file()
162
```
163
164
### Inline Images
165
166
Add images directly inline with alt text and optional tooltips.
167
168
```python { .api }
169
class MdUtils:
170
@staticmethod
171
def new_inline_image(text: str, path: str) -> str:
172
"""
173
Create inline images in markdown format.
174
175
Parameters:
176
- text (str): Alt text for the image
177
- path (str): Image path or URL
178
179
Returns:
180
str: Formatted inline image markdown
181
"""
182
183
class Image:
184
@staticmethod
185
def new_inline_image(text: str, path: str, tooltip: str = None) -> str:
186
"""
187
Create inline images with optional tooltips.
188
189
Parameters:
190
- text (str): Alt text for the image
191
- path (str): Image path or URL
192
- tooltip (str, optional): Tooltip text on hover
193
194
Returns:
195
str: Formatted inline image markdown
196
"""
197
```
198
199
**Usage Example:**
200
201
```python
202
from mdutils import MdUtils
203
from mdutils.tools import Image
204
205
md = MdUtils(file_name='inline_images_example')
206
207
# Basic inline images
208
md.new_header(level=1, title='Project Screenshots')
209
210
# Using MdUtils static method
211
logo_image = MdUtils.new_inline_image('Company Logo', './images/logo.png')
212
md.new_paragraph(f'Welcome to our platform: {logo_image}')
213
214
# Using Image class with tooltip
215
screenshot = Image.new_inline_image('Application Screenshot', './images/app-screenshot.png', 'Main application interface')
216
md.new_paragraph(f'Application overview: {screenshot}')
217
218
# Remote images
219
remote_image = MdUtils.new_inline_image('Remote Image', 'https://example.com/image.jpg')
220
md.new_paragraph(f'External resource: {remote_image}')
221
222
# Images in different contexts
223
md.new_header(level=2, title='Architecture Diagram')
224
diagram = Image.new_inline_image('System Architecture', './diagrams/architecture.svg', 'System component relationships')
225
md.write(diagram)
226
```
227
228
### Reference Images
229
230
Create reference-style images with automatic reference management.
231
232
```python { .api }
233
class MdUtils:
234
def new_reference_image(self, text: str, path: str, reference_tag: Optional[str] = None) -> str:
235
"""
236
Create reference-style images with automatic reference collection.
237
238
Parameters:
239
- text (str): Alt text for the image
240
- path (str): Image path or URL
241
- reference_tag (str, optional): Custom reference tag (defaults to text)
242
243
Returns:
244
str: Reference image marker (actual reference stored for document end)
245
"""
246
247
class Image:
248
def new_reference_image(self, text: str, path: str, reference_tag: str = None, tooltip: str = None) -> str:
249
"""
250
Create reference-style images with tooltip support.
251
252
Parameters:
253
- text (str): Alt text for the image
254
- path (str): Image path or URL
255
- reference_tag (str, optional): Custom reference identifier
256
- tooltip (str, optional): Tooltip text
257
258
Returns:
259
str: Reference image marker
260
"""
261
```
262
263
**Usage Example:**
264
265
```python
266
from mdutils import MdUtils
267
268
md = MdUtils(file_name='reference_images_example')
269
270
md.new_header(level=1, title='Project Gallery')
271
272
# Reference images with default tags
273
screenshot1 = md.new_reference_image('Dashboard View', './images/dashboard.png')
274
screenshot2 = md.new_reference_image('Settings Panel', './images/settings.png')
275
276
md.new_paragraph(f'The main interface consists of a {screenshot1} and {screenshot2}.')
277
278
# Reference images with custom tags
279
flowchart = md.new_reference_image('Process Flowchart', './diagrams/process-flow.png', 'process-diagram')
280
workflow = md.new_reference_image('Workflow Diagram', './diagrams/workflow.png', 'workflow-diagram')
281
282
md.new_paragraph(f'Understanding the {flowchart} and {workflow} is essential.')
283
284
# Multiple references to same image
285
icon = md.new_reference_image('Application Icon', './images/icon.png', 'app-icon')
286
icon_small = md.new_reference_image('Icon', './images/icon.png', 'icon-small')
287
288
md.new_paragraph(f'The {icon} appears in various sizes, including {icon_small}.')
289
290
# References automatically added to document end
291
md.create_md_file()
292
```
293
294
### Advanced Link and Image Patterns
295
296
Complex usage patterns combining links, images, and formatting for rich content.
297
298
**Image Links (Images as Links):**
299
300
```python
301
from mdutils import MdUtils
302
303
md = MdUtils(file_name='advanced_patterns')
304
305
# Create clickable images (manual approach)
306
md.new_header(level=2, title='Clickable Images')
307
308
# Method 1: Manual markdown combination
309
clickable_logo = '[](https://company.com)'
310
md.write(clickable_logo)
311
312
# Method 2: Combine image and link creation
313
image_part = MdUtils.new_inline_image('Product Screenshot', './images/product.png')
314
# Remove the ! to convert image to link format, then wrap in link
315
link_part = f'[{image_part[1:]}](https://product-demo.com)'
316
md.new_paragraph(f'Try the demo: {link_part}')
317
```
318
319
**Link Collections and Navigation:**
320
321
```python
322
from mdutils import MdUtils
323
324
md = MdUtils(file_name='navigation_patterns')
325
326
md.new_header(level=1, title='Quick Navigation')
327
328
# Create a navigation menu using links
329
nav_links = [
330
md.new_inline_link('#introduction', 'Introduction'),
331
md.new_inline_link('#features', 'Features'),
332
md.new_inline_link('#installation', 'Installation'),
333
md.new_inline_link('#usage', 'Usage'),
334
md.new_inline_link('#api-reference', 'API Reference')
335
]
336
337
md.new_paragraph(' | '.join(nav_links))
338
339
# External resource links
340
md.new_header(level=2, title='External Resources')
341
resources = {
342
'Documentation': 'https://docs.example.com',
343
'GitHub Repository': 'https://github.com/user/repo',
344
'Issue Tracker': 'https://github.com/user/repo/issues',
345
'Community Forum': 'https://forum.example.com'
346
}
347
348
for name, url in resources.items():
349
link = md.new_reference_link(url, name, name.lower().replace(' ', '-'))
350
md.new_line(f'- {link}')
351
```
352
353
**Image Galleries and Collections:**
354
355
```python
356
from mdutils import MdUtils
357
358
md = MdUtils(file_name='image_gallery')
359
360
md.new_header(level=1, title='Project Gallery')
361
362
# Create image gallery with descriptions
363
gallery_images = [
364
{'alt': 'Login Screen', 'path': './screenshots/login.png', 'desc': 'User authentication interface'},
365
{'alt': 'Dashboard', 'path': './screenshots/dashboard.png', 'desc': 'Main application dashboard'},
366
{'alt': 'Settings', 'path': './screenshots/settings.png', 'desc': 'Configuration options'},
367
{'alt': 'Reports', 'path': './screenshots/reports.png', 'desc': 'Analytics and reporting'}
368
]
369
370
for img in gallery_images:
371
md.new_header(level=3, title=img['alt'])
372
image_ref = md.new_reference_image(img['alt'], img['path'])
373
md.new_paragraph(f"{image_ref}")
374
md.new_paragraph(img['desc'])
375
376
# Before and after comparison
377
md.new_header(level=2, title='Before and After')
378
before_img = md.new_inline_image('Before Update', './images/before.png')
379
after_img = md.new_inline_image('After Update', './images/after.png')
380
381
# Create comparison table
382
comparison_data = [
383
['Before', 'After'],
384
[before_img, after_img]
385
]
386
md.new_table_array(data=comparison_data, text_align='center')
387
```
388
389
### Link and Image Management
390
391
Best practices for organizing and managing links and images in large documents.
392
393
**Usage Example:**
394
395
```python
396
from mdutils import MdUtils
397
398
md = MdUtils(file_name='link_management')
399
400
# Consistent reference tag naming
401
md.new_header(level=1, title='Best Practices Guide')
402
403
# Use descriptive reference tags
404
api_docs = md.new_reference_link('https://api.example.com/docs', 'API Documentation', 'api-docs')
405
user_guide = md.new_reference_link('https://guide.example.com', 'User Guide', 'user-guide')
406
troubleshooting = md.new_reference_link('https://help.example.com', 'Troubleshooting', 'troubleshooting')
407
408
md.new_paragraph(f'Essential resources: {api_docs}, {user_guide}, and {troubleshooting}.')
409
410
# Group related images with consistent naming
411
md.new_header(level=2, title='UI Screenshots')
412
ui_login = md.new_reference_image('Login Interface', './ui/login.png', 'ui-login')
413
ui_dashboard = md.new_reference_image('Dashboard View', './ui/dashboard.png', 'ui-dashboard')
414
ui_settings = md.new_reference_image('Settings Panel', './ui/settings.png', 'ui-settings')
415
416
md.new_paragraph(f'Interface progression: {ui_login} → {ui_dashboard} → {ui_settings}')
417
418
# Verify references before creating file
419
print("Total references:", len(md.reference.get_references()))
420
print("Reference keys:", list(md.reference.get_references().keys()))
421
422
md.create_md_file()
423
```