md-to-telegram

md-to-telegram

Convert LLM-style Markdown (GFM + LaTeX math) into Telegram-renderable output — in both Telegram formats — with a typed report of everything that had no Telegram equivalent.

• Targets Telegram HTML, MarkdownV2 (parse_mode), and Rich Markdown (the markdown field of InputRichMessage, Bot API 10.1 Rich Messages).
• Fully typed API; the result tells you exactly what was dropped (images, math, footnotes, unsupported HTML) and where.
• Generates an LLM prompt so a model writes convert-friendly Markdown.
• Understands Telegram-only directives (spoiler, underline, expandable quote).
• Dual ESM + CJS, no peer setup.

The conversion rules come straight from the specs in docs/: Telegram formatting, LLM Markdown, and the conversion mapping.

Install

pnpm add md-to-telegram   # or npm i / yarn add

Requires Node ≥ 22.18.

Usage

import { toTelegramHTML, toTelegramMarkdownV2 } from "md-to-telegram";

const md = "# Hello\n\nSome **bold** and a ![pic](https://x/y.png) and $a^2$.";

const { text, removed } = toTelegramHTML(md);
// text:    "<b>Hello</b>\n\nSome <b>bold</b> and a  and ."
// removed: [{ kind: "image", url: "https://x/y.png", alt: "pic", position: {…} },
//           { kind: "math", value: "a^2", inline: true, position: {…} }]

toTelegramMarkdownV2(md).text;
// "*Hello*\n\nSome *bold* and a  and \\."

convert is the same thing with an explicit format (handy when the target is dynamic):

import { convert } from "md-to-telegram";
convert(md, { format: "markdownv2" });

Rich Messages (Bot API 10.1)

For clients that support Rich Messages, Telegram renders headings, lists, tables, math, images, and footnotes natively — so there's almost nothing to drop. toTelegramRich produces the string for the markdown field of InputRichMessage:

import { toTelegramRich, validateRichMarkdown } from "md-to-telegram";

const { text, removed } = toTelegramRich(md);
// removed is always [] — Rich Markdown is GFM-compatible, so it's near pass-through.

// Length / structural limits are checked separately (it never splits for you):
const warnings = validateRichMarkdown(text); // RichLimitWarning[] (empty if within limits)

await bot.api.sendRichMessage(chatId, { markdown: text });

Use rich for capable clients and keep html / markdownv2 as the fallback. When you generate the source with an LLM, pass target: "rich" to buildTelegramPrompt so the model is told it may use images, math, tables, and footnotes. An expandable blockquote (> [!expandable]) becomes a collapsible <details> (label via the expandableSummary option).

Long messages (splitting)

Telegram rejects messages over a length limit (4096 for parse_mode, 32768 for Rich). splitMessage breaks rendered output into parts that fit without corrupting markup — it packs on block boundaries, re-wraps oversized code blocks, and closes/reopens any open tags or inline marks at a seam:

import { splitMessage, toTelegramHTML } from "md-to-telegram";

const { text } = toTelegramHTML(longMarkdown);
for (const part of splitMessage(text, { format: "html" })) {
  await bot.api.sendMessage(chatId, part, { parse_mode: "HTML" });
}

Pass maxLength to override the per-format default.

Streaming

Bot API 9.3+ can stream a reply with sendMessageDraft (and sendRichMessageDraft for Rich). sendMessageDraft takes parse_mode, so stream a formatted preview: convert the partial buffer each tick (toTelegramHTML(buffer)) and send it with parse_mode. This is safe because convert always emits valid markup even from half-written Markdown (an unclosed **bold stays literal until it closes — no 400s mid-stream). Reuse one non-zero draft_id so updates animate, then send the final converted message once. See examples/ai-sdk-grammy.ts for the full draft → finalize flow with the Vercel AI SDK + grammY.

Handling what was removed

removed is a discriminated union — narrow on kind to get exact, typed fields:

const { text, removed } = toTelegramHTML(md);

for (const item of removed) {
  switch (item.kind) {
    case "image":
      await bot.sendPhoto(chatId, item.url, { caption: item.alt });
      break;
    case "math":
      console.warn(`dropped ${item.inline ? "inline" : "block"} math: ${item.value}`);
      break;
    case "footnote": // item.identifier, item.variant, item.value
    case "html": // item.tagName, item.scope, item.value
      break;
  }
}

Recommended pipeline: LLM → Markdown → convert

The most reliable setup is to let the model write plain Markdown and convert it deterministically — no post-processing or "sanitizing" of model output needed. buildTelegramPrompt() produces a single, format-agnostic system prompt that keeps the model away from unconvertible constructs and teaches it the Telegram-only directives:

import { buildTelegramPrompt, toTelegramHTML } from "md-to-telegram";

const system = buildTelegramPrompt(); // "write Markdown, avoid images/math/...; you may use ||spoiler||, ..."
const markdown = await llm({ system, prompt: userTask });

const { text } = toTelegramHTML(markdown); // always valid Telegram HTML
await bot.sendMessage(chatId, text, { parse_mode: "HTML" });

Telegram-only directives

Standard Markdown can't express some Telegram entities, so this library understands a few small extensions (also documented in the generated prompt). They work in both output formats:

Directive	Markdown syntax	HTML	MarkdownV2
Spoiler	||text||	<tg-spoiler>	||text||
Underline	++text++	<u>	__text__
Expandable quote	a blockquote starting with a > [!expandable] line	<blockquote expandable>	**>…||

What maps to what

md-to-telegram re-serializes from a parsed AST, so Telegram entities are always well-formed and correctly escaped. Highlights:

• Direct: bold, italic, bold+italic, strikethrough, inline code, links, code blocks, blockquotes.
• Approximated: headings → bold; lists → •/numbered/☑·☐; tables → fixed-width block; thematic break → a rule line; nested blockquotes → flattened (Telegram can't nest them).
• Removed + reported (no Telegram equivalent): images, LaTeX math, footnotes, unsupported raw HTML. Opt into light degradation with options (images: "link", math: "raw", footnotes: "inline" | "append").

Note: __x__ is bold in Markdown but underline in Telegram MarkdownV2 — this library always emits bold as *x*, so it never silently becomes underline.

Options

All options are optional; defaults match docs/conversion-mapping.md.

Option	Default	Description
tables	"pre"	"pre" (fixed-width block) or "remove".
thematicBreak	a line of ─	A literal string, or "blank" for an empty line.
flattenBlockquotes	true	Flatten nested blockquotes to one level.
images	"remove"	"remove" or "link" (always reported either way).
math	"remove"	"remove" or "raw" (keep the LaTeX as code).
footnotes	"remove"	"remove", "inline", or "append".
collectRemoved	true	Populate result.removed.
listIndent	3	Spaces per nested-list level.
expandableSummary	"Details"	rich only: <summary> label for > [!expandable] quotes.

Releasing

CI (lint, typecheck, build, tests, mutation) runs on every PR. Releases use Changesets + npm trusted publishing (OIDC):

1. Add a changeset in your PR: pnpm changeset (pick the bump, write a summary).
2. Merging to main opens a "Version Packages" PR (bumps version + CHANGELOG.md).
3. Merging that PR publishes to npm automatically with provenance — no stored token.

First publish only (npm can't configure OIDC for a name that doesn't exist yet): add a temporary NPM_TOKEN secret, run the Bootstrap publish workflow once, configure the trusted publisher in the npm package settings, then delete the secret.

License

MIT Igor Katsuba