HTML entities parser for mtcute
NOTE: The syntax implemented here is incompatible with Bot API HTML.
Please read Syntax below for a detailed explanation
import { html } from '@mtcute/html-parser'
tg.sendText(
'me',
html`
Hello, <b>me</b>! Updates from the feed:<br>
${await getUpdatesFromFeed()}
`
)
@mtcute/html-parser
uses htmlparser2
under the hood, so the parser
supports nearly any HTML. However, since the text is still processed in a custom way for Telegram, the supported subset
of features is documented below:
Line breaks are not preserved, <br>
is used instead,
making the syntax very close to the one used when building web pages.
Multiple spaces and indents are collapsed (except in pre
), when you do need multiple spaces use
instead.
Inline entities are entities that are in-line with other text. We support these entities:
Name | Code | Result (visual) |
---|---|---|
Bold | <b>text</b> |
text |
Italic | <b>text</b> |
text |
Underline | <u>text</u> |
text |
Strikethrough | <s>text</s> |
|
Spoiler | <spoiler>text</spoiler> (or tg-spoiler ) |
N/A |
Monospace (code) | <code>text</code> |
text |
Text link | <a href="https://google.com">Google</a> |
|
Text mention | <a href="tg://user?id=1234567">Name</a> |
N/A |
Custom emoji | <emoji id="12345">😄</emoji> (or <tg-emoji emoji-id="..."> ) |
N/A |
Note:
<strong>
,<em>
,<ins>
,<strike>
,<del>
are not supported because they are redundant
Note: It is up to the client to look up user's input entity by ID for text mentions. In most cases, you can only use IDs of users that were seen by the client while using given storage.
Alternatively, you can explicitly provide access hash like this:
<a href="tg://user?id=1234567&hash=abc">Name</a>
, whereabc
is user's access hash written as a hexadecimal integer. Order of the parameters does matter, i.e.tg://user?hash=abc&id=1234567
will not be processed as expected.
The only block entity that Telegram supports is <pre>
, therefore it is the only tag we support too.
Optionally, language for <pre>
block can be specified like this:
<pre language="typescript">export type Foo = 42</pre>
Code | Result (visual) |
---|---|
<pre>multiline\ntext</pre> |
multiline |
<pre language="javascript"> |
export default 42 |
HTML is a nested language, and so is this parser. It does support nested entities, but overlapped entities will not work as expected!
Overlapping entities are supported in unparse()
, though.
Code | Result (visual) |
---|---|
<b>Welcome back, <i>User</i>!</b> |
Welcome back, User! |
<b>bold <i>and</b> italic</i> |
bold and italic ⚠️ word "italic" is not actually italic! |
<b>bold <i>and</i></b><i> italic</i> ⚠️ this is how unparse() handles overlapping entities |
bold and italic |
Being a tagged template literal, html
supports interpolation.
You can interpolate one of the following:
string
- will not be parsed, and appended to plain text as-is
html
as a simple function: html... ${html('**bold**')} ...
number
- will be converted to string and appended to plain text as-isTextWithEntities
or MessageEntity
- will add the text and its entities to the output. This is the type returned by html
itself:const bold = html`**bold**`
const text = html`Hello, ${bold}!`
null
, undefined
, false
) - will be ignoredNote that because of interpolation, you almost never need to think about escaping anything, since the values are not even parsed as HTML, and are appended to the output as-is.