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

npm install @vcc-community/telegramify-markdown
# or
yarn add @vcc-community/telegramify-markdown

Usage

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

const markdownText =
  '**Hello** *world*! Visit our [website](https://example.com). 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 });

ParseResult Interface

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

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

MessageEntity Interface

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

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](url) -> { "_": "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

markdownToTelegramEntities(markdownString: string): ParseResult

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