@telegraf/entity

Convert Telegram entities to HTML or Markdown.

⚠️ Before you start using this module, consider using copyMessage instead.

This module will produce Telegram-compatible HTML or MarkdownV2, however it is better to simply pass the text and entities back to Telegram rather than converting to HTML or Markdown.

This module is really for the rare cases where you want to convert Telegram-formatted text for consumption outside of Telegram.

npm install @telegraf/entity

Simple usage

Usage is very straightforward!

import { toHTML, toMarkdownV2 } from "@telegraf/entity";
// if Deno:
// import { toHTML, toMarkdownV2 } from "https://deno.land/x/telegraf_entity";

bot.on(message("text"), async ctx => {
    const html = toHTML(ctx.message); // convert text to HTML string
    const md = toMarkdownV2(ctx.message); // convert text to MarkdownV2 string
});

Both functions will also just work with captioned messages like photos.

bot.on(message("photo"), async ctx => {
    const html = toHTML(ctx.message); // convert caption to HTML string
    const md = toMarkdownV2(ctx.message); // convert caption to MarkdownV2 string
});

You can also directly pass just a text and entities object:

toHTML({ text: '...', entities: [...] }); // HTML string

Advanced usage

By default we produce HTML or Markdown compatible with Telegram, you may want to serialise differently. This module exposes a way to do this: serialiseWith. To use this, you must first implement a serialiser with the following type:

/**
 * @param match will always be a string
 * @param entity will be undefined for plain text; otherwise the entity
 * @param escape whether or not to escape the inner text
 * @note Serialiser will be called recursively for nested entities, so we don't want to double-serialise
 */
function myHTMLSerialiser (match: string, entity?: MessageEntity, escape = true): string {
    // implement
}

Refer to the implementation of the builtin serialisers for something you can simply copy-paste and edit until you're satisfied.

The builtin escapers are also exported for your convenience:

import { escapers } from "@telegraf/entity";

escapers.HTML(text); // HTML escaped text
escapers.MarkdownV2(text); // escaped for Telegram's MarkdownV2