Telegram Markdown Pipe Table Rendering & CJK Alignment
Overview
A comprehensive engineering guide and solution for rendering Markdown pipe tables in Telegram bots without broken layouts. It covers Bot API native rendering, CJK character width compensation, standalone cron delivery bypass, and automatic mobile card degradation.
When to Use & When NOT to Use
When to Use
- Formatting LLM tabular output for Telegram bots (Hermes, python-telegram-bot, Aiogram).
- Fixing character misalignment caused by mixed Chinese/Japanese/Korean and ASCII characters in Monospace tables.
- Preventing wide tables (>5 columns) from turning into mangled text on mobile Telegram clients.
When NOT to Use
- Standard web browsers or HTML-native rendering environments where CSS handles table layouts.
- Platforms with native rich table APIs (e.g. Discord embeds or Slack blocks).
The Telegram Table Truth & Solutions Matrix
| Delivery Path |
Native Table Support |
What Actually Happens |
Best Solution |
Bot API sendRichMessage |
✅ Yes |
Renders native GFM pipe tables |
Pass raw markdown directly to sendRichMessage endpoint |
Standard sendMessage (MarkdownV2) |
❌ No |
Telegram has no table syntax in MarkdownV2; ` |
` is just a char |
| Standalone Cron / Webhook |
⚠️ Partial |
Often converted to bullet points by intermediary adapters |
Direct Bot API webhook or use telegram-table-renderer package |
Python CJK Padding Algorithm
import unicodedata
def get_cjk_width(text: str) -> int:
"""Calculate visual width in monospace terminal font."""
return sum(2 if unicodedata.east_asian_width(c) in ('W', 'F') else 1 for c in text)
def pad_cjk_cell(text: str, target_width: int, align: str = 'left') -> str:
current_width = get_cjk_width(text)
pad = max(0, target_width - current_width)
if align == 'right':
return ' ' * pad + text
elif align == 'center':
left = pad // 2
return ' ' * left + text + ' ' * (pad - left)
return text + ' ' * pad
Common Pitfalls
- Tables with ≥6 columns on mobile: Telegram mobile screens are too narrow for 6-column tables; automatically degrade tables with >5 columns into structured bullet cards (
🔹 Key: Value).
- MarkdownV2 character escaping errors: In MarkdownV2 mode, unescaped reserved characters (
_, *, [, ], (, ), ~, >, #, +, -, =, |, {, }, ., !) cause delivery failure.
- Double delivery on standalone scripts: When writing direct Bot API delivery scripts, ensure output is not printed to stdout if cron delivery is also enabled.
Verification Checklist
1---2name: telegram-pipe-table-rendering3description: Use when sending Markdown tables to Telegram, resolving table degradation, CJK East Asian character alignment, and mobile viewport wrapping.4license: MIT5---67# Telegram Markdown Pipe Table Rendering & CJK Alignment89## Overview1011A comprehensive engineering guide and solution for rendering Markdown pipe tables in Telegram bots without broken layouts. It covers **Bot API native rendering, CJK character width compensation, standalone cron delivery bypass, and automatic mobile card degradation**.1213## When to Use & When NOT to Use1415### When to Use16- Formatting LLM tabular output for Telegram bots (Hermes, python-telegram-bot, Aiogram).17- Fixing character misalignment caused by mixed Chinese/Japanese/Korean and ASCII characters in Monospace tables.18- Preventing wide tables (>5 columns) from turning into mangled text on mobile Telegram clients.1920### When NOT to Use21- Standard web browsers or HTML-native rendering environments where CSS handles table layouts.22- Platforms with native rich table APIs (e.g. Discord embeds or Slack blocks).2324## The Telegram Table Truth & Solutions Matrix2526| Delivery Path | Native Table Support | What Actually Happens | Best Solution |27|---|:---:|---|---|28| **Bot API `sendRichMessage`** | ✅ Yes | Renders native GFM pipe tables | Pass raw markdown directly to `sendRichMessage` endpoint |29| **Standard `sendMessage` (MarkdownV2)** | ❌ No | Telegram has no table syntax in MarkdownV2; `|` is just a char | Pre-format with CJK padding or degrade wide tables to cards |30| **Standalone Cron / Webhook** | ⚠️ Partial | Often converted to bullet points by intermediary adapters | Direct Bot API webhook or use `telegram-table-renderer` package |3132## Python CJK Padding Algorithm3334```python35import unicodedata3637def get_cjk_width(text: str) -> int:38 """Calculate visual width in monospace terminal font."""39 return sum(2 if unicodedata.east_asian_width(c) in ('W', 'F') else 1 for c in text)4041def pad_cjk_cell(text: str, target_width: int, align: str = 'left') -> str:42 current_width = get_cjk_width(text)43 pad = max(0, target_width - current_width)44 if align == 'right':45 return ' ' * pad + text46 elif align == 'center':47 left = pad // 248 return ' ' * left + text + ' ' * (pad - left)49 return text + ' ' * pad50```5152## Common Pitfalls53541. **Tables with ≥6 columns on mobile**: Telegram mobile screens are too narrow for 6-column tables; automatically degrade tables with >5 columns into structured bullet cards (`🔹 Key: Value`).552. **MarkdownV2 character escaping errors**: In MarkdownV2 mode, unescaped reserved characters (`_`, `*`, `[`, `]`, `(`, `)`, `~`, `>`, `#`, `+`, `-`, `=`, `|`, `{`, `}`, `.`, `!`) cause delivery failure.563. **Double delivery on standalone scripts**: When writing direct Bot API delivery scripts, ensure output is not printed to stdout if cron delivery is also enabled.5758## Verification Checklist5960- [ ] Table borders align vertically in Telegram desktop and web clients.61- [ ] CJK characters count as 2 width units during cell padding calculation.62- [ ] Tables with >5 columns gracefully convert to card format when mobile mode is enabled.
shali10