A lightweight TypeScript library for seamlessly transforming standard Markdown into Telegram's MarkdownV2 format. Built for developers who want reliable Markdown-to-Telegram conversion without the hassle.
Working with Telegram's MarkdownV2 format can be frustrating - special characters need escaping, formatting rules are strict, and one wrong character breaks everything. This library handles all the complexity, letting you focus on your bot's functionality.
bun install telegram-markdown-v2
Or with npm:
npm install telegram-markdown-v2
import { convert } from 'telegram-markdown-v2'; const markdown = ` # Hello World This is **bold text** and *italic text*. - List item 1 - List item 2 `; const telegramMarkdown = convert(markdown); console.log(telegramMarkdown);
Transforms standard Markdown into Telegram MarkdownV2 format.
Parameters:
markdown: The input Markdown stringunsupportedTagsStrategy: Optional strategy for handling unsupported tags ('keep'|'escape'|'remove'). Default:'keep'
Returns: Formatted string ready for Telegram's parse_mode: 'MarkdownV2'
| Element | Input | Telegram Output |
|---|---|---|
| Bold | **text** |
*text* |
| Italic | *text* |
_text_ |
| Underline | <u>text</u> |
__text__ |
~~text~~ |
~text~ |
|
| Spoiler | <span class="tg-spoiler">text</span> |
` |
Inline Code |
`code` |
`code` |
| Links | [text](url) |
[text](url) |
| Block Quotes | > quote |
Configurable (keep/escape/remove) |
| Code Blocks | lang code |
code |
| Lists | - item |
• item |
| Headings | # Title |
*Title* |
type UnsupportedTagsStrategy = 'escape' | 'remove' | 'keep';
Strategy Options:
'keep'(default): Preserve unsupported elements as-is'escape': Escape special characters in unsupported elements'remove': Remove unsupported elements entirely
import { convert } from 'telegram-markdown-v2'; const input = "Check out this **amazing** library with *great* features!"; const output = convert(input); // Result: "Check out this *amazing* library with _great_ features\\!"
const codeExample = ` Here's some JavaScript code: \`\`\`javascript function hello() { console.log("Hello, world!"); } \`\`\` `; const formatted = convert(codeExample); // Ready to send via Telegram Bot API
const listExample = ` ## Todo List - Create awesome library - Write documentation - Publish to npm Visit [our repo](https://github.com/example/telegram-markdown-v2) `; const telegramReady = convert(listExample);
import { convert } from 'telegram-markdown-v2'; // Keep unsupported tags as-is (default) const keepResult = convert('> This is a blockquote', 'keep'); // Result: "> This is a blockquote\n" // Escape special characters in unsupported tags const escapeResult = convert('> This is a blockquote', 'escape'); // Result: "\\> This is a blockquote\n" // Remove unsupported tags entirely const removeResult = convert('> This is a blockquote', 'remove'); // Result: ""
// Underline support const underline = convert('This is <u>underlined</u> text'); // Result: "This is __underlined__ text\n" // Spoiler support const spoiler = convert('This is <span class="tg-spoiler">hidden</span> text'); // Result: "This is ||hidden|| text\n" // Custom emoji and user mentions const mentions = convert('[John](tg://user?id=123) sent '); // Result: "[John](tg://user\\?id\\=123) sent [👍](tg://emoji\\?id\\=456)\n"
The library automatically escapes Telegram's special characters: _*[]()~#+-=|{}.!`
Telegram limits messages to 4096 characters. You'll need to implement message splitting in your application.
If your Markdown doesn't render correctly, check for unmatched formatting marks or nested styles.
Elements like tables, blockquotes, and HTML tags can be handled using the unsupportedTagsStrategy parameter.
# Install dependencies bun install # Run tests bun test # Build for production bun run build # Type checking bun run typecheck # Linting bun run lint
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
MIT © 2025
Inspired by the Python telegramify-markdown library, reimagined for the TypeScript ecosystem with modern tooling and better performance.