telegramify-markdown

Effortlessly convert raw Markdown to Telegram plain text + MessageEntity pairs.

Say goodbye to MarkdownV2 escaping headaches! This library parses Markdown (including LLM output, GitHub READMEs, etc.) and produces (text, entities) tuples that can be sent directly via the Telegram Bot API — no parse_mode needed.

• No matter the format or length, it can be easily handled!
• Entity offsets are measured in UTF-16 code units, exactly as Telegram requires.
• We also support LaTeX-to-Unicode conversion, expandable block quotes, and Mermaid diagram rendering.
• Built on pyromark (Rust pulldown-cmark bindings) for speed and correctness.

[!NOTE] v1.0.0 introduces a new entity-based output: convert() returns (str, list[MessageEntity]). The 0.x functions markdownify() and standardize() are still available and return MarkdownV2 strings as before.

👀 Use case

🪄 Quick Start

Install

Requires Python 3.10+.

# uv (recommended)
uv add telegramify-markdown
uv add "telegramify-markdown[mermaid]"

# pip
pip install telegramify-markdown
pip install "telegramify-markdown[mermaid]"

# PDM
pdm add telegramify-markdown
pdm add "telegramify-markdown[mermaid]"

# Poetry
poetry add telegramify-markdown
poetry add "telegramify-markdown[mermaid]"

🤔 What you want to do?

• If you just want to send static text and don't want to worry about formatting → use convert()
• If you are developing an LLM application or need to send potentially super-long text → use telegramify()
• If you need streaming output (token-by-token, like ChatGPT typing) → use DraftStream (private) or EditStream (group)
• If you need to split convert() output manually → use split_entities()
• If your middleware only supports parse_mode="MarkdownV2" (no entities parameter) → use markdownify()
• If you need to split long MarkdownV2 output safely → use split_markdownv2()
• If you need finer control over the reverse conversion → use entities_to_markdownv2()
• If you want Telegram Bot API 10.1 structured Rich Messages → use richify()
• If you need to split long Rich Messages automatically → use telegramify_rich()

convert() — single message

from telebot import TeleBot
from telegramify_markdown import convert

bot = TeleBot("YOUR_TOKEN")

md = "**Bold**, _italic_, and `code`."
text, entities = convert(md)

bot.send_message(
    chat_id,
    text,
    entities=[e.to_dict() for e in entities],
)

No parse_mode parameter — Telegram reads the entities directly.

richify() — Bot API 10.1 Rich Message

For Telegram Bot API 10.1 structured messages, use richify() to produce an InputRichMessage payload. This is a parallel output backend: it does not change convert().

import requests
from telegramify_markdown import richify

md = """
# Report

| Metric | Value |
| --- | --- |
| Speed | **42 ms** |

$$E = mc^2$$
"""

rich_message = richify(md)

requests.post(
    f"https://api.telegram.org/bot{token}/sendRichMessage",
    json={
        "chat_id": chat_id,
        "rich_message": rich_message.to_dict(),
    },
    timeout=30,
)

Use richify(markdown, mode="markdown") when you want Telegram to parse the input as Telegram Rich Markdown directly.

telegramify_rich() — long Rich Messages with automatic splitting

For long Markdown that exceeds Telegram's Rich Message limits (32768 bytes or 500 blocks), telegramify_rich() splits the output into multiple sendable chunks:

import requests
from telegramify_markdown import telegramify_rich

md = very_long_markdown  # e.g. LLM output

items = telegramify_rich(md)
for item in items:
    requests.post(
        f"https://api.telegram.org/bot{token}/sendRichMessage",
        json={
            "chat_id": chat_id,
            "rich_message": item.to_dict(),
        },
        timeout=30,
    )

Each chunk is a valid, self-contained Rich HTML document. Splitting happens at block boundaries — never in the middle of a tag or nested structure.

For development changes to Rich Message output, run the live contract test before opening a PR:

TELEGRAM_BOT_TOKEN=... TELEGRAM_CHAT_ID=... pdm run test-live-rich

The test sends a real sendRichMessage request and requires Telegram to return Message.rich_message.

DraftStream / EditStream — streaming LLM output (Bot API 9.3+)

For token-by-token LLM output, DraftStream sends intermediate drafts via sendMessageDraft / sendRichMessageDraft, then finalizes with the complete message. Works in private chats. For group chats (no draft API), EditStream sends then edits the message.

import asyncio
from telegramify_markdown.stream import DraftStream

async def stream_response(chat_id, token, llm_tokens):
    async def send_draft(payload):
        # Call sendRichMessageDraft with payload.rich_message.to_dict()
        ...

    async def send_final(payload):
        # Call sendRichMessage with payload.rich_message.to_dict()
        ...

    async with DraftStream(
        send_draft=send_draft,
        send_final=send_final,
        mode="rich",           # "rich" | "entity"
        interval=0.3,          # seconds between draft updates
        thinking_delay=0.5,    # show "Thinking..." before first content
        keepalive_timeout=25.0,  # prevent draft expiry
        config=None,           # entity mode: RenderConfig for symbols (EditStream too)
    ) as stream:
        async for tok in llm_tokens:
            stream.feed(tok)

For group/channel chats (draft API unavailable):

from telegramify_markdown.stream import EditStream

async with EditStream(
    send_message=my_send_fn,   # async (payload) -> message_id
    edit_message=my_edit_fn,   # async (message_id, payload) -> None
    mode="rich",
    interval=1.0,              # >= 1.0s enforced (Telegram edit rate limit)
) as stream:
    async for tok in llm_tokens:
        stream.feed(tok)

telegramify() — long messages, code files, diagrams

For LLM output or long documents, telegramify() splits text, extracts code blocks as files, and renders Mermaid diagrams as images:

import asyncio
from telebot import TeleBot
from telegramify_markdown import telegramify
from telegramify_markdown.content import ContentType

bot = TeleBot("YOUR_TOKEN")

md = """
# Report

Here is some analysis with **bold** and _italic_ text.

```python
print("hello world")
```

And a diagram:

```mermaid
graph TD
    A-->B
```
"""

async def send():
    results = await telegramify(md, max_message_length=4090)
    for item in results:
        if item.content_type == ContentType.TEXT:
            bot.send_message(
                chat_id,
                item.text,
                entities=[e.to_dict() for e in item.entities],
            )
        elif item.content_type == ContentType.PHOTO:
            bot.send_photo(
                chat_id,
                (item.file_name, item.file_data),
                caption=item.caption_text or None,
                caption_entities=[e.to_dict() for e in item.caption_entities] or None,
            )
        elif item.content_type == ContentType.FILE:
            bot.send_document(
                chat_id,
                (item.file_name, item.file_data),
                caption=item.caption_text or None,
                caption_entities=[e.to_dict() for e in item.caption_entities] or None,
            )

asyncio.run(send())

split_entities() — manual splitting

If you use convert() but need to split long output yourself:

from telegramify_markdown import convert, split_entities

text, entities = convert(long_markdown)

for chunk_text, chunk_entities in split_entities(text, entities, max_utf16_len=4096):
    bot.send_message(
        chat_id,
        chunk_text,
        entities=[e.to_dict() for e in chunk_entities],
    )

split_entities() omits empty and whitespace-only chunks because Telegram rejects them as empty messages.

markdownify() — direct Markdown to MarkdownV2

If your middleware only supports parse_mode="MarkdownV2" and cannot pass entities, use markdownify() for a one-step conversion:

from telegramify_markdown import markdownify

mdv2 = markdownify("**Bold** and `code`")
bot.send_message(chat_id, mdv2, parse_mode="MarkdownV2")

standardize() is an alias for markdownify(), kept for 0.x compatibility.

split_markdownv2() — split MarkdownV2 safely

If your middleware only supports parse_mode="MarkdownV2", split by the rendered MarkdownV2 length, not only by the plain text length:

from telegramify_markdown import convert, split_markdownv2

text, entities = convert(long_markdown)

for mdv2 in split_markdownv2(text, entities, max_utf16_len=4096):
    bot.send_message(chat_id, mdv2, parse_mode="MarkdownV2")

entities_to_markdownv2() — reverse conversion to MarkdownV2

If you already have (text, entities) from convert() and need a MarkdownV2 string:

from telegramify_markdown import convert, entities_to_markdownv2

text, entities = convert("**Bold** and `code`")
mdv2 = entities_to_markdownv2(text, entities)

bot.send_message(chat_id, mdv2, parse_mode="MarkdownV2")

This handles all MarkdownV2 escaping rules correctly (different escaping for normal text, code/pre blocks, and URLs).

⚙️ Configuration

Customize heading symbols, link symbols, list markers, expandable citation behavior, and Mermaid rendering:

from telegramify_markdown.config import get_runtime_config

cfg = get_runtime_config()
cfg.markdown_symbol.heading_level_1 = "📌"
cfg.markdown_symbol.link = "🔗"
cfg.markdown_symbol.unordered_list_item = "-"   # default "⦁"; try "•", "*", …
cfg.markdown_symbol.ordered_list_suffix = "."   # renders "1. item"; ")" gives "1) item"
cfg.cite_expandable = True  # Long quotes become expandable_blockquote
cfg.mermaid.width = 1280
cfg.mermaid.scale = 2
cfg.mermaid.theme = "default"
cfg.mermaid.image_type = "webp"

# For clean output without emoji heading prefixes:
# cfg.markdown_symbol.heading_level_1 = ""
# cfg.markdown_symbol.heading_level_2 = ""
# cfg.markdown_symbol.heading_level_3 = ""
# cfg.markdown_symbol.heading_level_4 = ""

List markers are plain text and carry no entity. Task list items keep using task_completed / task_uncompleted and replace the list marker entirely.

get_runtime_config() returns a process-global config. Setting it once at startup is the common case. It is shared mutable state, so a bot that varies symbols per chat must not mutate it inside a handler — concurrent requests would read each other's values. Use an independent config instead and pass it in:

from telegramify_markdown import RenderConfig, telegramify

cfg = RenderConfig.isolated()          # library defaults, independent
# cfg = get_runtime_config().copy()    # or: start from the current global values
cfg.markdown_symbol.unordered_list_item = "-"

boxes = await telegramify(markdown, config=cfg)

config= is accepted by convert(), convert_with_segments(), markdownify(), standardize(), and telegramify() (which also applies cfg.mermaid to rendered diagrams). richify() and telegramify_rich() take no config — Rich HTML emits structural tags and reads no symbols.

See docs/prd/render-config.md for the full contract.

telegramify() picks up Mermaid settings from the runtime config. The default Mermaid width is 1000.

📖 API Reference

convert(markdown, *, latex_escape=True) -> tuple[str, list[MessageEntity]]

Synchronous. Converts a Markdown string to plain text and a list of MessageEntity objects.

Returns (text, entities) where text is plain text and entities is a list of MessageEntity.

telegramify(content, *, max_message_length=4096, latex_escape=True) -> list[Text | File | Photo]

Async. Full pipeline: converts Markdown, splits long messages, extracts code blocks as files, renders Mermaid diagrams as images.

Returns an ordered list of Text, File, or Photo objects.

split_entities(text, entities, max_utf16_len) -> list[tuple[str, list[MessageEntity]]]

Split text + entities into chunks within a UTF-16 length limit. Splits at newline boundaries; entities spanning a split point are clipped into both chunks. Empty and whitespace-only chunks are omitted because Telegram rejects them as empty messages.

markdownify(content, *, latex_escape=True) -> str

Synchronous. Converts Markdown directly to a Telegram MarkdownV2 string. Equivalent to entities_to_markdownv2(*convert(content)).

standardize(content, *, latex_escape=True) -> str

Alias for markdownify(), kept for 0.x compatibility.

richify(markdown, *, mode="html", is_rtl=None, skip_entity_detection=None, latex_escape=False) -> InputRichMessage

Synchronous. Converts Markdown to a Telegram Bot API 10.1 InputRichMessage.

richify() returns an InputRichMessage object with .to_dict() for Bot API payloads. In HTML mode it emits Telegram Rich HTML for paragraphs, headings, inline formatting, links, lists, block quotes, tables, code blocks, images with HTTP(S) URLs, custom emoji images, and math tags.

telegramify_rich(markdown, *, mode="html", is_rtl=None, skip_entity_detection=None, latex_escape=False) -> list[RichMessage]

Synchronous. Converts Markdown to a list of sendable Rich Message chunks, each within Telegram limits (32768 UTF-8 bytes, 500 top-level blocks).

Returns list[RichMessage] where each item has .to_dict() for the Bot API.

split_rich(rich_message) -> list[InputRichMessage]

Split a single InputRichMessage into multiple chunks within Telegram limits. Useful when you already have a payload (e.g. from richify() on very long input) and only need splitting.

entities_to_markdownv2(text, entities=None) -> str

Reverse conversion: takes plain text and entities, returns a MarkdownV2 string with correct escaping. Useful when you already have (text, entities) from convert() and need a MarkdownV2 string.

split_markdownv2(text, entities=None, max_utf16_len=4096) -> list[str]

Split text + entities into Telegram MarkdownV2 strings within a rendered UTF-16 length limit. Use this instead of split_entities() when sending with parse_mode="MarkdownV2".

MessageEntity

@dataclasses.dataclass(slots=True)
class MessageEntity:
    type: str           # "bold", "italic", "code", "pre", "text_link", etc.
    offset: int         # Start position in UTF-16 code units
    length: int         # Length in UTF-16 code units
    url: str | None     # For "text_link" entities
    language: str | None       # For "pre" entities (code block language)
    custom_emoji_id: str | None  # For "custom_emoji" entities
    user: dict | None   # For "text_mention" entities
    unix_time: int | None       # For "date_time" entities
    date_time_format: str | None  # For "date_time" entities

    def to_dict(self) -> dict: ...

InputRichMessage

@dataclasses.dataclass(slots=True)
class InputRichMessage:
    html: str | None
    markdown: str | None
    is_rtl: bool | None
    skip_entity_detection: bool | None

    def to_dict(self) -> dict: ...

Content Types

utf16_len(text) -> int

Returns the length of a string in UTF-16 code units (what Telegram uses for offsets).

🔨 Supported Markdown Features

• Headings (Levels 1-6: H1-H2 bold+underline, H3-H4 bold, H5-H6 italic; H1-H4 with emoji prefix)
• **Bold**, *Italic*, ~~Strikethrough~~ (a single ~, as in ~5 min, stays literal)
• ||Spoiler||
• [Links](url) and ![Images](url)
• Telegram custom emoji ![emoji](tg://emoji?id=...)
• Inline code and fenced code blocks
• Block quotes > (with expandable citation support)
• Tables (rendered as monospace pre blocks)
• Ordered and unordered lists
• Task lists - [x] / - [ ]
• Horizontal rules ---
• LaTeX math \(...\) and \[...\] (converted to Unicode)
• Mermaid diagrams (rendered as images, requires [mermaid] extra)
• Telegram Bot API 10.1 Rich Message output via richify()

🤖 For AI Coding Assistants

This project provides llms.txt and llms-full.txt for AI assistant context. Copy the relevant file into your assistant's context (e.g. CLAUDE.md, Cursor Rules) for accurate code generation.

Critical rules:

• Pass entities as [e.to_dict() for e in entities] — never as JSON string
• Never set parse_mode when sending with entities — they are mutually exclusive
• richify() returns InputRichMessage for sendRichMessage, not text + entities
• Entity offsets are UTF-16 code units. Use utf16_len() to measure.

🧸 Acknowledgement

This library is inspired by npm:telegramify-markdown.

LaTeX escape is inspired by latex2unicode and @yym68686.

📜 License

This project is licensed under the MIT License — see the LICENSE file for details.