telegram_markdown_v2/lib.rs
1//! Convert Markdown into Telegram **MarkdownV2**.
2//!
3//! Telegram's MarkdownV2 is a restricted dialect with its own escaping rules. This crate
4//! takes a Markdown document and renders it into a string suitable to be sent with
5//! Telegram's `parse_mode = MarkdownV2`.
6//!
7//! The main entry points are [`convert`] (default behavior) and [`convert_with_strategy`]
8//! (custom handling for unsupported constructs).
9//!
10//! ## Basic usage
11//!
12//! ```rust
13//! # fn main() -> telegram_markdown_v2::Result<()> {
14//! use telegram_markdown_v2::convert;
15//!
16//! let out = convert("Hello world!")?;
17//! assert_eq!(out, "Hello world\\!\n");
18//! # Ok(())
19//! # }
20//! ```
21//!
22//! ## Unsupported constructs
23//!
24//! Telegram MarkdownV2 does not support some Markdown/HTML constructs (e.g. blockquotes,
25//! tables, and raw HTML blocks). Use [`UnsupportedTagsStrategy`] to decide what to do
26//! with such input:
27//!
28//! - [`UnsupportedTagsStrategy::Keep`]: keep the unsupported content as-is.
29//! - [`UnsupportedTagsStrategy::Escape`]: escape the unsupported content as plain text.
30//! - [`UnsupportedTagsStrategy::Remove`]: drop the unsupported content entirely.
31//!
32//! ```rust
33//! # fn main() -> telegram_markdown_v2::Result<()> {
34//! use telegram_markdown_v2::{convert_with_strategy, UnsupportedTagsStrategy};
35//!
36//! let out = convert_with_strategy("> test", UnsupportedTagsStrategy::Escape)?;
37//! assert_eq!(out, "\\> test\n");
38//! # Ok(())
39//! # }
40//! ```
41//!
42//! ## Telegram-specific extensions
43//!
44//! Outside inline/fenced code, the converter recognizes:
45//!
46//! - `<u>…</u>` as underline (`__…__`)
47//! - `<span class="tg-spoiler">…</span>` as spoiler (`||…||`)
48mod convert;
49mod definitions;
50mod errors;
51mod handlers;
52mod types;
53mod utils;
54
55pub use convert::{convert, convert_with_strategy};
56pub use errors::{Error, Result};
57pub use types::{Definition, TextType, UnsupportedTagsStrategy};