DOCSEARCHbyAlgolia
Submit Docs

mdutils 1.8.1

repository·master·Indexed 42 days ago

https://github.com/didix21/mdutils

A Python package for creating formatted Markdown files from code. It provides tools for generating structured reports, documentation, and logs, featuring support for Atx and Setext headers, tables, nested lists, checkbox lists, and Table of Contents generation. It includes utilities for text formatting (bold, italics, code), inline and reference links/images, and HTML-based image resizing and alignment.

Tokens
9.5K
Snippets
38
Records
50
Agent score
50%

What's inside mdutils

  1. Overview of mdutils

    master
    mdutils is a Python package designed to simplify the creation of Markdown files from Python code. It provides a set of tools to format text results into structured Markdown, making it easier to generate well-formatted documentation or reports directly from your Python execution workflows.

  2. Explore the mdutils.tools submodules

    master

    The mdutils.tools package provides specialized utility modules for manipulating and generating specific Markdown elements. You can use these submodules to handle complex Markdown structures programmatically.

    Available submodules include:

    • mdutils.tools.Header: For managing header levels and structures.
    • mdutils.tools.Html: For integrating HTML elements into Markdown.
    • mdutils.tools.Image: For handling image syntax and embedding.
    • mdutils.tools.Link: For managing hyperlinks and reference links.
    • mdutils.tools.MDList: For generating various list types (ordered, unordered, etc.).
    • mdutils.tools.Table: For constructing Markdown tables.
    • mdutils.tools.TableOfContents: For generating Table of Contents structures.
    • mdutils.tools.TextUtils: For text-based manipulations and formatting.

  3. Format Markdown text and structure

    master

    You can use mdutils to apply various formatting styles and structural elements to your Markdown documents:

    Text Formatting

    • Bold and Italics
    • Text color (Note: Support for text color depends on the CSS of the viewer; for example, GitHub does not support text color).

    Headers

    • Atx style: Headers from levels 1 through 6 (e.g., # Header 1).
    • Setext style: Headers of levels 1 and 2.

    Structural Elements

    • Tables: Create Markdown tables.
    • Table of Contents: Automatically generate a table of contents.
    • Links: Add hyperlinks to the document.
    • Images: Add images using both standard Markdown syntax and HTML syntax.

  4. Initialize and create a Markdown file

    master

    To use mdutils, first instantiate the MdUtils class with a file_name and a title. After defining your content using various methods, you must call create_md_file() to actually write the file to disk.

    Note: Some formatting features like text coloring or centering may not be visible in certain Markdown viewers (like GitHub) due to CSS limitations.

    from mdutils.mdutils import MdUtils

# Initialize the file object
mdFile = MdUtils(file_name='Example_Markdown', title='Markdown File Example')

# ... add content here ...

# Final step to write the file
mdFile.create_md_file()

  5. Write and Read Markdown files with mdutils

    master
    The mdutils library provides capabilities to create, read, and manipulate Markdown files. You can write new files, read existing ones, and append data to the end of a file. Additionally, you can use markers to place text at specific locations within a document.

  6. Initialize and create a Markdown file with MdUtils

    master

    To start generating a Markdown file, instantiate the MdUtils class with a file_name and a title. After adding your content (headers, paragraphs, etc.), you must call create_md_file() to write the file to disk. This should be the final command in your script.

    from mdutils.mdutils import MdUtils

# Initialize the file
mdFile = MdUtils(file_name='Example_Markdown', title='Markdown File Example')

# ... add content using other methods ...

# Finalize and write the file
mdFile.create_md_file()

  9. Use markers to place content anywhere

    master

    By default, mdutils appends content to the end of the file. To place content in a specific location, use the marker system.

    1. create_marker(text_marker): Generates a unique marker string and adds it to the document.
    2. place_text_using_marker(text, marker): Replaces the marker with the provided text.

    Most content methods (new_table, new_paragraph, write, etc.) accept a marker argument. If provided, the content is inserted at the marker's position instead of being appended.

    from mdutils import MdUtils

md = MdUtils(file_name='Marker_Example')

# 1. Create a marker
my_marker = md.create_marker('my_special_spot')

# 2. Add some content at the start
md.new_paragraph("This is at the top.")

# 3. Use the marker to place a table in the middle
md.new_table(columns=1, rows=1, text=['Middle Table'], marker=my_marker)

# 4. Add more content
md.new_paragraph("This is at the bottom.")

  10. Add and resize HTML images in Markdown

    master

    You can insert images with specific dimensions into a Markdown file using Html.image passed into mdFile.new_paragraph(). The size parameter accepts several formats to control width and height:

    • Width only: Use the numeric value (e.g., '200').
    • Height only: Prefix the value with x (e.g., 'x300').
    • Both width and height: Use the format 'WIDTHxHEIGHT' (e.g., '300x300').
    # Change width to 200
mdFile.new_paragraph(Html.image(path=path, size='200'))

# Change height to 300
mdFile.new_paragraph(Html.image(path=path, size='x300'))

# Change both width and height to 300x300
mdFile.new_paragraph(Html.image(path=path, size='300x300'))

  12. Generate a Table of Contents

    master

    If you have defined headers (specifically levels 1 and 2), you can generate a Table of Contents. This should typically be called near the end of your code, before create_md_file().

    Parameters:

    • table_title: The title for the TOC section.
    • depth: The maximum header level to include in the TOC.
    mdFile.new_table_of_contents(table_title='Contents', depth=2)