or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced.mdcore-document.mdheaders-toc.mdindex.mdlinks-images.mdlists.mdtables.mdtext-formatting.md
tile.json

tessl/pypi-mdutils

A comprehensive Python library for programmatically creating and manipulating Markdown files with support for headers, tables, lists, images, links, and text formatting.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/mdutils@1.8.x

To install, run

npx @tessl/cli install tessl/pypi-mdutils@1.8.0

index.mddocs/

MDUtils

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.

Package Information

  • Package Name: mdutils
  • Language: Python
  • Installation: pip install mdutils
  • Repository: https://github.com/didix21/mdutils
  • Documentation: http://mdutils.readthedocs.io

Core Imports

from mdutils import MdUtils

Import specific components:

from mdutils import MdUtils, Header, Link, Image, TextUtils, Table, TableOfContents, Html, MDList
# Note: MDCheckbox must be imported from tools
from mdutils.tools import MDCheckbox

Import utilities directly:

from mdutils.fileutils import fileutils
# Or import directly:
from mdutils.fileutils.fileutils import MarkDownFile
from mdutils.tools import Header, Link, Image, TextUtils, Table, TableOfContents, Html, MDList, MDCheckbox

Basic Usage

from mdutils import MdUtils

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

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

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

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

# Generate the markdown file
mdFile.create_md_file()

# Or get the content as a string
content = mdFile.get_md_text()
print(content)

Architecture

MDUtils follows a modular architecture with specialized tool classes:

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

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

Capabilities

Core Document Management

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

class MdUtils:
    def __init__(self, file_name: str, title: str = "", author: str = "", title_header_style: str = "setext"): ...
    def create_md_file(self) -> MarkDownFile: ...
    def get_md_text(self) -> str: ...
    def read_md_file(self, file_name: str) -> str: ...
    def write(self, text: str = "", bold_italics_code: str = "", color: str = "black", align: str = "", marker: str = "", wrap_width: int = 0) -> str: ...
    def new_paragraph(self, text: str = "", bold_italics_code: str = "", color: str = "black", align: str = "", wrap_width: int = 0) -> str: ...
    def new_line(self, text: str = "", bold_italics_code: str = "", color: str = "black", align: str = "", wrap_width: int = 0) -> str: ...

Core Document Management

Text Formatting

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

class TextUtils:
    @staticmethod
    def bold(text: str) -> str: ...
    @staticmethod
    def italics(text: str) -> str: ...
    @staticmethod
    def inline_code(text: str) -> str: ...
    @staticmethod
    def text_color(text: str, color: str = "black") -> str: ...
    @staticmethod
    def center_text(text: str) -> str: ...
    @staticmethod
    def text_format(text: str, bold_italics_code: str = "", color: str = "black", align: str = "") -> str: ...

Text Formatting

Headers and Table of Contents

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

class MdUtils:
    def new_header(self, level: int, title: str, style: str = "atx", add_table_of_contents: str = "y", header_id: str = "") -> str: ...
    def new_table_of_contents(self, table_title: str = "Table of contents", depth: int = 1, marker: str = "") -> str: ...

class Header:
    def __init__(self, level: int, title: str, style: HeaderStyle, header_id: str = None): ...
    @staticmethod
    def atx(level: AtxHeaderLevel, title: str, header_id: str = None) -> str: ...
    @staticmethod
    def setext(level: SetextHeaderLevel, title: str) -> str: ...

Headers and Table of Contents

Tables

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

class MdUtils:
    def new_table(self, columns: int, rows: int, text: List[str], text_align: Optional[Union[str, list]] = "center", marker: str = "") -> str: ...
    def new_table_array(self, data: List[List[str]], text_align: Optional[Union[str, list]] = None, marker: str = "") -> str: ...

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

Tables

Lists

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

class MdUtils:
    def new_list(self, items: List[str], marked_with: str = "-"): ...
    def new_checkbox_list(self, items: List[str], checked: bool = False): ...

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

class MDCheckbox:
    def __init__(self, items, checked: bool = False): ...
    def get_md(self) -> str: ...

Lists

Links and Images

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

class MdUtils:
    def new_inline_link(self, link: str, text: Optional[str] = None, bold_italics_code: str = "", align: str = "") -> str: ...
    def new_reference_link(self, link: str, text: str, reference_tag: Optional[str] = None, bold_italics_code: str = "", align: str = "") -> str: ...
    @staticmethod
    def new_inline_image(text: str, path: str) -> str: ...
    def new_reference_image(self, text: str, path: str, reference_tag: Optional[str] = None) -> str: ...

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

class Image:
    @staticmethod
    def new_inline_image(text: str, path: str, tooltip: str = None) -> str: ...
    def new_reference_image(self, text: str, path: str, reference_tag: str = None, tooltip: str = None) -> str: ...

Links and Images

Advanced Features

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

class MdUtils:
    def create_marker(self, text_marker: str) -> str: ...
    def place_text_using_marker(self, text: str, marker: str) -> str: ...
    def insert_code(self, code: str, language: str = "") -> str: ...

class Html:
    @staticmethod
    def paragraph(text: str, align: str = None) -> str: ...
    @classmethod
    def image(cls, path: str, size: str = None, align: str = None) -> str: ...

class MarkDownFile:
    def __init__(self, name="", dirname: Optional[str] = None): ...
    def rewrite_all_file(self, data: str): ...
    def append_end(self, data: str): ...
    @staticmethod
    def read_file(file_name: str) -> str: ...

Advanced Features

Types

# Enums for header styling
class HeaderStyle(Enum):
    ATX = "atx"
    SETEXT = "setext"

class AtxHeaderLevel(Enum):
    TITLE = 1        # H1
    HEADING = 2      # H2  
    SUBHEADING = 3   # H3
    SUBSUBHEADING = 4 # H4
    MINORHEADING = 5  # H5
    LEASTHEADING = 6  # H6

class SetextHeaderLevel(Enum):
    TITLE = 1    # H1
    HEADING = 2  # H2

# Exception types
class SizeBadFormat(Exception):
    def __init__(self, message): ...