p2dmd

p2dmd is a Python library by addy that converts standard Markdown to Telegram MarkdownV2, so you can send richly formatted messages through the Telegram Bot API without manually escaping every special character.

---

Why p2dmd?

Telegram's MarkdownV2 format requires that almost every special character (_ * [ ] ( ) ~ \ > # + - = | { } . !`) be escaped with a backslash. Doing this by hand is tedious and error-prone. p2dmd handles all of that automatically, while also converting LaTeX math to readable Unicode and splitting oversized code blocks.

---

Installation

pip install p2dmd

---

Quick Start

from p2dmd import escape

text = """
# My Heading

This is **bold**, _italic_, __underlined__, and ~~strikethrough~~.

Hide a secret with ||spoiler text||.

Inline code: `print("hello")`

```python
def greet(name):
    return f"Hello, {name}!"

A blockquote

• Item A
• Item B
  • Nested item

1. First step
2. Second step

Telegram Docs

Math: ( \varphi(35) = 35 \left(1 - \frac{1}{5}\right) \left(1 - \frac{1}{7}\right) ) """

result = escape(text)

Now send it with your bot

import requests requests.post( "https://api.telegram.org/bot<YOUR_TOKEN>/sendMessage", json={ "chat_id": "<CHAT_ID>", "text": result, "parse_mode": "MarkdownV2" } )

---

## Supported Syntax

| Input (Markdown) | Output (Telegram MarkdownV2) | Notes |
|---|---|---|
| `**bold**` | `*bold*` | Bold text |
| `_italic_` | `_italic_` | Italic text |
| `__underline__` | `__underline__` | Underlined text |
| `~~strike~~` | `~strike~` | Strikethrough |
| `\|\|spoiler\|\|` | `\|\|spoiler\|\|` | Hidden/spoiler text |
| `` `code` `` | `` `code` `` | Inline code |
| ` ```lang ... ``` ` | ` ```lang ... ``` ` | Code block (with language) |
| `[text](url)` | `[text](url)` | Clickable link |
| `![alt](url)` | `[alt](url)` | Image as link (Telegram doesn't embed images in text) |
| `> quote` | `> quote` | Blockquote |
| `# Heading` | `▎*Heading*` | Section heading |
| `- item` / `* item` | `• item` | Bullet list |
| `1. item` | `1\. item` | Numbered list |
| `\( expr \)` | Unicode math | Inline LaTeX |
| `\[ expr \]` | Unicode math (block) | Display LaTeX |

---

## API Reference

### `escape(text, flag=0, italic=True)`

The main function. Takes a Markdown string and returns a Telegram MarkdownV2-safe string.

```python
from p2dmd import escape

result = escape(text)

Parameters

Name	Type	Default	Description
text	str	required	Markdown text to convert
flag	int	0	Set to 1 to preserve literal \\ double backslashes in output
italic	bool	True	Set to False to skip _italic_ conversion (useful if your text uses underscores in variable names)

Returns: str — the escaped, Telegram-ready string.

---

Sending Long Messages

Telegram has a 4096 character limit per message. p2dmd automatically splits code blocks longer than 2300 characters. After calling escape(), check for the split marker \n@|@|@|@\n\n and send each part as a separate message:

from p2dmd import escape

result = escape(my_long_text)

parts = result.split("\n@|@|@|@\n\n")
for part in parts:
    requests.post(
        "https://api.telegram.org/bot<TOKEN>/sendMessage",
        json={"chat_id": chat_id, "text": part, "parse_mode": "MarkdownV2"}
    )

---

LaTeX / Math Support

p2dmd converts LaTeX expressions to Unicode characters, making math readable even in plain text:

LaTeX	Unicode
\varphi(35) = 35(1 - \frac{1}{5})(1 - \frac{1}{7})	ϕ(35) = 35(1 - ⅕)(1 - 1/7)
\alpha + \beta = \gamma	α + β = γ
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}	∑ᵢ₌₁ⁿ i = n(n+1)/2
\sqrt{2}	√2̄
a^2 + b^2 = c^2	a² + b² = c²

Supported: Greek letters, operators, arrows, fractions, subscripts, superscripts, and over 300 symbols. See src/latex2unicode.py for the full symbol table.

---

Publishing to PyPI (Trusted Publishing)

This repo uses OIDC Trusted Publishing — no PyPI API token needed.

One-time setup on PyPI:

1. Go to your project on pypi.org → Publishing → Add a new publisher
2. Fill in:
   • GitHub owner: pooraddyy
   • Repository name: p2dmd
   • Workflow filename: main.yml
   • Environment name: pypi
3. On GitHub, create a Repository Environment named pypi (Settings → Environments)

To publish a release:

git tag v1.0.0
git push origin v1.0.0

The workflow triggers automatically on version tags and publishes to PyPI.

---

Reference

• Telegram MarkdownV2 spec: https://core.telegram.org/bots/api#markdownv2-style
• Inspired by: https://github.com/skoropadas/telegramify-markdown

License

GPLv3 — free to use, modify, and distribute under the same license.