mdutils

1.8.1 · active · verified Sun Apr 12

mdutils is a useful Python package for programmatically creating Markdown files. It provides methods to generate headers, lists, tables, links, images, and format text while executing Python code. The current version is 1.8.1, and the library is actively maintained with regular updates including new features, bug fixes, and general maintenance.

Warnings

gotcha The `text_align` parameter for methods like `new_table` was enhanced in v1.3.1 to accept a list of strings for individual column alignment, in addition to a single string (`'left'`, `'center'`, `'right'`) for global alignment. Code expecting only a single string type for `text_align` might need adjustment if more granular control is desired or if type-checking is strict.
Fix: Ensure `text_align` is a single string (e.g., `'center'`) for global alignment, or a list of strings (e.g., `['left', 'center', 'right']`) for column-specific alignment.
gotcha Before v1.8.1, using bold text (e.g., `**text**`) as an item in `new_list` could cause the list formatting to break. This bug was fixed in v1.8.1, so previous workarounds are no longer necessary.
Fix: Upgrade to v1.8.1 or later. If unable to upgrade, avoid starting list items with Markdown bold syntax when using `new_list`.
deprecated The `new_line()` method previously added extra spaces in some scenarios. This was fixed in v1.7.0. If your application relied on or accounted for these extra spaces in its output parsing, its behavior might change.
Fix: Upgrade to v1.7.0 or later to ensure correct spacing. Review any downstream parsing logic if you were handling unexpected spaces from `new_line()`.
gotcha Prior to v1.2.2, table of contents links generated by `MdUtils` might not work correctly if headers contained special characters. This issue was resolved, improving the robustness of TOC generation.
Fix: Upgrade to v1.2.2 or later to ensure TOC links with special characters are correctly rendered. Older versions might require manual sanitization of header titles for reliable TOC links.

Install

pip install mdutils Install with pip

Imports

MdUtils
```
from mdutils.mdutils import MdUtils
```

Quickstart

This quickstart demonstrates how to initialize the `MdUtils` class, add various Markdown elements like headers, paragraphs, lists, and tables, and then generate the `.md` file. The `create_md_file()` method is always the last call to write the content to disk.

from mdutils.mdutils import MdUtils

# Create a Markdown file object
mdFile = MdUtils(file_name='example_markdown', title='My Example Document')

# Add a header
mdFile.new_header(level=1, title='Introduction')
mdFile.new_paragraph("This is an example of a Markdown file created using the mdutils library.")

# Add a list
mdFile.new_header(level=2, title='Features')
items = [
    'Create Headers',
    'Generate Tables',
    'Add Lists',
    'Insert Links and Images'
]
mdFile.new_list(items=items, marked_with='-')

# Add a table
mdFile.new_header(level=2, title='Data Table')
list_of_strings = [
    'Header 1', 'Header 2', 'Header 3',
    'Row 1, Col 1', 'Row 1, Col 2', 'Row 1, Col 3',
    'Row 2, Col 1', 'Row 2, Col 2', 'Row 2, Col 3'
]
mdFile.new_table(columns=3, rows=3, text=list_of_strings, text_align='center')

# Finalize and create the file
mdFile.create_md_file()
print("Markdown file 'example_markdown.md' created successfully.")

view raw JSON →