Telegramify Markdown


A lightweight TypeScript utility to convert Markdown into a text string and an array of MessageEntity objects, suitable for use with the Telegram Bot API.

Description

This library parses common Markdown syntax and transforms it into a plain text representation along with a list of entities that describe the formatting. This output is designed to be directly usable with Telegram's sendMessage method (or similar methods) that accept text and entities parameters for rich message formatting.

It aims to cover the most common Markdown features that have a direct equivalent in Telegram's supported message entities.

Features

- Converts Markdown to plain text and a list of Telegram MessageEntity objects.
- Supports common Markdown: bold, italic, strikethrough, inline code, pre-formatted code blocks (with language hint), and links.
- Handles nested Markdown formatting.
- Calculates UTF-16 code unit offsets and lengths for entities, as required by Telegram.
- Written in TypeScript, providing type safety and autocompletion.

Installation

``bash
npm install @vcc-community/telegramify-markdown


or


yarn add @vcc-community/telegramify-markdown
`

Usage

``typescript
import {
markdownToTelegramEntities,
ParseResult,
MessageEntity,
} from '@vcc-community/telegramify-markdown';

const markdownText =
'Hello world! Visit our website. Check out this code and a block:\n`javascript\nconsole.log("Hello from a code block!");\n`';

const result: ParseResult = markdownToTelegramEntities(markdownText);

console.log('Text:', result.text);
console.log('Entities:', JSON.stringify(result.entities, null, 2));

/*
Expected output:

Text: Hello world! Visit our website. Check out this code and a block:
console.log("Hello from a code block!");

Entities: [
{
"_": "messageEntityBold",
"offset": 0,
"length": 5
},
{
"_": "messageEntityItalic",
"offset": 6,
"length": 5
},
{
"_": "messageEntityTextUrl",
"offset": 24,
"length": 7,
"url": "https://example.com"
},
{
"_": "messageEntityCode",
"offset": 49,
"length": 4
},
{
"_": "messageEntityPre",
"offset": 66,
"length": 38,
"language": "javascript"
}
]
*/

// You can then use this with a Telegram bot library, for example:
// bot.sendMessage(chatId, result.text, { entities: result.entities });
``

$3

The markdownToTelegramEntities function returns an object conforming to the ParseResult interface:

`typescript
interface ParseResult {
text: string; // The plain text version of the Markdown.
entities: MessageEntity[]; // An array of formatting entities.
}
`

$3

Each entity in the entities array conforms to the MessageEntity interface, similar to Telegram's own type:

`typescript
interface MessageEntity {
_: string; // The type of the entity (e.g., 'messageEntityBold', 'messageEntityTextUrl').
offset: number; // Offset of the entity in UTF-16 code units.
length: number; // Length of the entity in UTF-16 code units.
url?: string; // Optional: For 'messageEntityTextUrl', the URL.
language?: string; // Optional: For 'messageEntityPre', the programming language.
}
`

Supported Markdown & Corresponding Entities

This library converts the following Markdown features into their respective MessageEntity types:

- Bold: text or __text__ -> { "_": "messageEntityBold", offset, length }
- _Italic_: text or _text_ -> { "_": "messageEntityItalic", offset, length }
- ~~Strikethrough~~: ~~text~~ -> { "_": "messageEntityStrike", offset, length }
- Inline Code: code -> { "_": "messageEntityCode", offset, length }
- Code Block:
``
`lang
code block
`
``
-> { "_": "messageEntityPre", offset, length, language: "lang" }
(If lang is not provided, language will be an empty string.)
- Link: text -> { "_": "messageEntityTextUrl", offset, length, url: "url" }
- > Blockquote: > text -> { "_": "messageEntityBlockquote", offset, length } (Note: Telegram renders blockquotes with a vertical bar prefix; the entity marks the quoted text.)

Unsupported Markdown syntax will generally be rendered as plain text without a corresponding entity.

API

$3

Converts a Markdown string into a ParseResult object containing the plain text and an array of MessageEntity objects.

- markdownString (string): The input Markdown text.
- Returns: ParseResult - An object with text and entities properties.

Development

- Clone the repository: git clone https://github.com/Vibe-Coding-Community/telegramify-markdown.git
- Install dependencies: npm install
- Run tests: npm test
- Lint code: npm run lint
- Format code: npm run format
- Build: npm run build`

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

License

MIT