markdown-hero 0.1.0

Markdown processing utilities: strip, chunk, append, break, Word export, lint, and more.

markdown_hero

A Python library for processing Markdown — cleanup, chunking, Word (.docx) export, concatenation, splitting by delimiters, and validation.

Compatible with Python 3.10+. Target dialect: GitHub Flavored Markdown (GFM).

Installation

pip install markdown_hero
# with a real tokenizer (tiktoken) for accurate chunking:
pip install "markdown_hero[tokenizers]"

Main functions

Function	What it does
strip(md, ...)	Reduces Markdown to normalized plain text (no diacritics, no punctuation, lowercase).
extract_chunks(md, purpose=...)	Splits the document respecting heading hierarchy, with rich metadata.
word_format(md, output)	Exports to .docx with a fixed set of professional styles.
markdown_append(*paths, output)	Concatenates files with heading shift and frontmatter merge.
markdown_break(path, delimiter, ...)	Splits a file into N+1 parts. Accepts string, regex, or list.
markdown_merge(*paths, output)	Smart append with section dedupe and TOC generation.
extract_*	Frontmatter, links, images, tables, code blocks, headings, TOC.
lint(md)	Detects skipped headings, duplicate anchors, unclosed fences.
CLI markdown-hero	Command-line access.

See docs/reference.md for the full technical reference and docs/helpers.md for the index of internal utilities.

Quick example

from markdown_hero import strip, extract_chunks, word_format

text = "**Hello!** See [docs](https://x). p=2 captures both."
print(strip(text))
# "hello see docs p2 captures both"

chunks = extract_chunks(open("doc.md").read(), purpose="rag", max_tokens=512)
word_format("doc.md", "doc.docx")

CLI

markdown-hero strip doc.md -o doc.txt
markdown-hero chunk doc.md --purpose rag --max-tokens 512 -o chunks.json
markdown-hero word doc.md -o doc.docx
markdown-hero append a.md b.md -o merged.md
markdown-hero break doc.md "---" --output-dir parts/
markdown-hero lint doc.md

Documentation

• Technical reference: docs/reference.md
• Internal helpers index: docs/helpers.md
• Release history: CHANGELOG.md
• How to contribute: CONTRIBUTING.md
• Security policy: SECURITY.md

Contact

Questions, suggestions, and reports:

• Email: [e-mail]
• Always include the prefix Markdown Hero: in the subject line so the message is routed correctly.

For security vulnerabilities follow the instructions in SECURITY.md (same email, same subject prefix).

License

MIT © 2026 Bernardo Leandro.