CtrlK
BlogDocsLog inGet started
Tessl Logo

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.

80

1.90x
Overview
Eval results
Files

headers-toc.mddocs/

Headers and Table of Contents

Header creation with multiple styles and automated table of contents generation with customizable depth and positioning. MDUtils supports both ATX-style (#) and Setext-style (underlined) headers, along with automatic table of contents generation from header structures.

Capabilities

Header Creation

Create headers with configurable levels, styles, and automatic table of contents integration.

class MdUtils:
    def new_header(self, level: int, title: str, style: str = "atx", add_table_of_contents: str = "y", header_id: str = "") -> str:
        """
        Add a new header to the markdown document.

        Parameters:
        - level (int): Header level (1-6 for ATX, 1-2 for Setext)
        - title (str): Header text content
        - style (str): Header style ('atx' for #-style, 'setext' for underlined)
        - add_table_of_contents (str): Include in TOC ('y' or 'n')
        - header_id (str, optional): HTML ID for the header (extended markdown)

        Returns:
        str: Formatted header string
        """

Usage Example:

from mdutils import MdUtils

md = MdUtils(file_name='headers_example')

# ATX-style headers (default)
md.new_header(level=1, title='Main Title')           # # Main Title
md.new_header(level=2, title='Section Header')      # ## Section Header  
md.new_header(level=3, title='Subsection')          # ### Subsection

# Setext-style headers
md.new_header(level=1, title='Main Title', style='setext')      # Main Title\n==========
md.new_header(level=2, title='Section Header', style='setext')  # Section Header\n--------------

# Headers with IDs (for linking)
md.new_header(level=2, title='Advanced Topics', header_id='advanced')

# Headers excluded from table of contents
md.new_header(level=3, title='Internal Note', add_table_of_contents='n')

Header Tool Classes

Direct access to header creation tools for advanced header manipulation and styling.

class Header:
    def __init__(self, level: int, title: str, style: HeaderStyle, header_id: str = None):
        """
        Initialize a header object.

        Parameters:
        - level (int): Header level (1-6)
        - title (str): Header text
        - style (HeaderStyle): ATX or SETEXT style enum
        - header_id (str, optional): HTML ID for the header
        """

    def __str__(self) -> str:
        """
        Get string representation of the header.

        Returns:
        str: Formatted header string
        """

    @staticmethod
    def atx(level: AtxHeaderLevel, title: str, header_id: str = None) -> str:
        """
        Create ATX-style header (# ## ### etc.).

        Parameters:
        - level (AtxHeaderLevel): Header level enum (TITLE=1 through LEASTHEADING=6)
        - title (str): Header text
        - header_id (str, optional): HTML ID for the header

        Returns:
        str: ATX-formatted header
        """

    @staticmethod  
    def setext(level: SetextHeaderLevel, title: str) -> str:
        """
        Create Setext-style header (underlined).

        Parameters:
        - level (SetextHeaderLevel): TITLE=1 (===) or HEADING=2 (---)
        - title (str): Header text

        Returns:
        str: Setext-formatted header
        """

    @staticmethod
    def header_anchor(text: str, link: str = None) -> str:
        """
        Create internal anchor link to header.

        Parameters:
        - text (str): Display text for the link
        - link (str, optional): Header ID to link to (defaults to text)

        Returns:
        str: Markdown link to header anchor
        """

Usage Example:

from mdutils import MdUtils
from mdutils.tools import Header, HeaderStyle, AtxHeaderLevel, SetextHeaderLevel

md = MdUtils(file_name='header_tools_example')

# Using Header class directly
h1 = Header(level=1, title='Introduction', style=HeaderStyle.ATX)
md.write(str(h1))

h2_setext = Header(level=2, title='Overview', style=HeaderStyle.SETEXT)
md.write(str(h2_setext))

# Using static methods
atx_header = Header.atx(AtxHeaderLevel.SUBHEADING, 'Technical Details')
setext_header = Header.setext(SetextHeaderLevel.HEADING, 'Summary')

md.write(atx_header)
md.write(setext_header)

# Creating header anchors
anchor_link = Header.header_anchor('Go to Introduction', 'introduction')
md.write(f'Reference: {anchor_link}')

Table of Contents Generation

Automatically generate table of contents from document headers with customizable depth and positioning.

class MdUtils:
    def new_table_of_contents(self, table_title: str = "Table of contents", depth: int = 1, marker: str = "") -> str:
        """
        Generate table of contents from document headers.

        Parameters:
        - table_title (str): Title for the table of contents section
        - depth (int): Maximum header depth to include (1-6)
        - marker (str, optional): Marker for positioning TOC at specific location

        Returns:
        str: Formatted table of contents
        """

Usage Example:

from mdutils import MdUtils

md = MdUtils(file_name='toc_example')

# Add some headers first
md.new_header(level=1, title='Introduction')
md.new_paragraph('Introduction content...')

md.new_header(level=2, title='Getting Started')
md.new_paragraph('Getting started content...')

md.new_header(level=3, title='Installation')
md.new_paragraph('Installation instructions...')

md.new_header(level=2, title='Advanced Usage')
md.new_paragraph('Advanced usage content...')

md.new_header(level=3, title='Configuration')
md.new_paragraph('Configuration details...')

# Generate table of contents
md.new_table_of_contents()  # Default: includes all levels, placed after title

# Generate TOC with custom title and depth
md.new_table_of_contents(table_title="Contents", depth=2)  # Only H1 and H2

# Generate TOC at specific location using marker
marker = md.create_marker('toc_location')
md.new_table_of_contents(table_title="Navigation", depth=3, marker=marker)

Table of Contents Tool Classes

Direct access to table of contents generation tools for advanced TOC customization.

class TableOfContents:
    def create_table_of_contents(self, array_of_title_contents: List[str], depth: int = 1) -> str:
        """
        Create table of contents from a list of header titles.

        Parameters:
        - array_of_title_contents (List[str]): Nested list structure of headers
        - depth (int): Maximum depth to include in TOC

        Returns:
        str: Formatted table of contents markdown
        """

    def _loop_through(self, elements, tab: str = "", depth: int = 1) -> str:
        """
        Internal method for processing nested header lists.

        Parameters:
        - elements: Nested list structure to process
        - tab (str): Current indentation level
        - depth (int): Current processing depth

        Returns:
        str: Processed TOC section
        """

Usage Example:

from mdutils import MdUtils
from mdutils.tools import TableOfContents

md = MdUtils(file_name='toc_tools_example')

# Create headers and build TOC manually
md.new_header(level=1, title='Chapter 1')
md.new_header(level=2, title='Section 1.1')
md.new_header(level=2, title='Section 1.2')
md.new_header(level=1, title='Chapter 2')

# Access the internal title structure
toc_generator = TableOfContents()
toc_content = toc_generator.create_table_of_contents(md._table_titles, depth=2)

md.write(toc_content)

Header Styling Enums

Enumerations for header levels and styles to ensure type safety and consistency.

class HeaderStyle(Enum):
    ATX = "atx"      # Hash-style headers (# ## ###)
    SETEXT = "setext" # Underlined headers (=== ---)

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: underlined with ===
    HEADING = 2  # H2: underlined with ---

Usage Example:

from mdutils import MdUtils
from mdutils.tools import Header, HeaderStyle, AtxHeaderLevel, SetextHeaderLevel

md = MdUtils(file_name='enum_example')

# Using enums for type safety
title_header = Header.atx(AtxHeaderLevel.TITLE, 'Document Title')
section_header = Header.atx(AtxHeaderLevel.HEADING, 'Main Section')
subsection_header = Header.atx(AtxHeaderLevel.SUBHEADING, 'Subsection')

md.write(title_header)
md.write(section_header) 
md.write(subsection_header)

# Setext style with enums
setext_title = Header.setext(SetextHeaderLevel.TITLE, 'Major Title')
setext_heading = Header.setext(SetextHeaderLevel.HEADING, 'Section Heading')

md.write(setext_title)
md.write(setext_heading)

Complete TOC Workflow

Comprehensive example showing header creation and table of contents generation workflow.

Usage Example:

from mdutils import MdUtils

# Create document with title
md = MdUtils(file_name='complete_doc', title='User Manual', title_header_style='setext')

# Add structured content with headers
md.new_header(level=1, title='Overview')
md.new_paragraph('This manual covers all aspects of the software.')

md.new_header(level=2, title='Key Features')
md.new_paragraph('The software includes the following features:')

md.new_header(level=3, title='User Interface')
md.new_paragraph('Clean and intuitive interface design.')

md.new_header(level=3, title='Performance')
md.new_paragraph('Optimized for speed and efficiency.')

md.new_header(level=2, title='Installation Requirements')
md.new_paragraph('System requirements and installation steps.')

md.new_header(level=1, title='Getting Started')
md.new_paragraph('Quick start guide for new users.')

md.new_header(level=2, title='First Steps')
md.new_paragraph('Basic operations to get you up and running.')

md.new_header(level=2, title='Configuration')
md.new_paragraph('How to configure the software for your needs.')

md.new_header(level=1, title='Advanced Topics')
md.new_paragraph('Advanced features and customization options.')

# Generate comprehensive table of contents
md.new_table_of_contents(table_title='Table of Contents', depth=3)

# Create the final document
md.create_md_file()

Install with Tessl CLI

npx tessl i tessl/pypi-mdutils

docs

advanced.md

core-document.md

headers-toc.md

index.md

links-images.md

lists.md

tables.md

text-formatting.md

tile.json