Markdown Normalization

pymdtools.normalize provides helpers to normalize Markdown strings and Markdown files. It uses the Mistune integration layer to parse Markdown and render it back to a consistent Markdown representation.

Common Usage

Normalize an in-memory string:

from pymdtools.normalize import md_beautifier

text = md_beautifier("# Title\n\nBody\n")

Normalize a Markdown file in place:

from pymdtools.normalize import md_file_beautifier

md_file_beautifier("README.md", backup_option=True)

Public API

Markdown normalization helpers.

This module provides the small public surface used by pymdtools to make Markdown content consistent:

• md_beautifier() normalizes an in-memory Markdown string;

• md_file_beautifier() applies the same transformation to a Markdown file.

Normalization is implemented as a Markdown-to-Markdown rendering pass through the Mistune 3 integration layer. File-oriented work delegates path validation, backup creation, encoding-aware reads, and writes to pymdtools.common.

Examples

Normalize a string:

>>> md_beautifier("# Title\n\nBody\n\n")
'# Title\n\nBody'

Normalize a file in place:

>>> md_file_beautifier("README.md", backup_option=True)
'...README.md'

pymdtools.normalize.md_beautifier(text: object) → str

Normalize Markdown text.

The input is parsed by Mistune and rendered back to Markdown with pymdtools.mistune_integration.MdRenderer. The result is stripped of leading and trailing whitespace, matching the historical behavior of this function.

This helper is intentionally small: it does not resolve include directives, variables, or file references. Those transformations live in pymdtools.instruction.

Parameters:

text – Markdown text to normalize.

Returns:

Normalized Markdown text.

Raises:

TypeError – If text is not a string.

pymdtools.normalize.md_file_beautifier(filename: str | PathLike[str] | Path, backup_option: bool = True, filename_ext: str = '.md', *, backup_ext: str = '.bak', read_encoding: str | None = None, write_encoding: str = 'utf-8') → str

Normalize a Markdown file in place.

The file is validated, read, optionally backed up, normalized with md_beautifier(), and written back with the requested encoding.

Backups are created before writing and use pymdtools.common.create_backup(). The file is written through pymdtools.common.set_file_content(), so the write path follows the common module’s atomic-write behavior.

Parameters:

• filename – Markdown file to normalize.

• backup_option – Whether to create a backup before overwriting the file.

• filename_ext – Expected Markdown extension, including the leading dot.

• backup_ext – Backup extension used when backup_option is true.

• read_encoding – Encoding used to read the file. None triggers automatic detection in pymdtools.common.

• write_encoding – Encoding used to write the normalized file.

Returns:

Normalized absolute filename as a string.

Raises:

• FileNotFoundError – If filename does not exist.

• IsADirectoryError – If filename is not a regular file.

• ValueError – If the file extension is unexpected or the file is empty.

• OSError – Propagated from filesystem helpers.