📖 API Reference
Markdown entities parser for mtcute
NOTE: The syntax implemented here is not compatible with Bot API Markdown, nor MarkdownV2.
Please read Syntax below for a detailed explanation
import { md } from '@mtcute/markdown-parser'
tg.sendText(
'me',
md`
Hello, **me**! Updates from the feed:
${await getUpdatesFromFeed()}
`
)
Inline entities are defined by some tag surrounding some text, and processing them simply strips their tag.
Supported entities:
**
__
--
(NON-STANDARD)~~
||
(NON-STANDARD)`
Unlike CommonMark, we use the symbol itself and not its count. Thus, using
*
(asterisk) will always produce bold, and using_
(underscore) will always produce italic.This eliminates a lot of confusion, like:
_bold_
→ bold,**italic**
→ italic
Code | Result (visual) | Result (as HTML) |
---|---|---|
**bold** |
bold | <b>bold</b> |
__italic__ |
italic | <i>italic</i> |
--underline-- |
underline | <u>underline</u> |
~~strikethrough~~ |
<s>strikethrough</s> |
|
||spoiler|| |
N/A | <spoiler>spoiler</spoiler> |
*whatever* |
*whatever* | *whatever* |
_whatever_ |
_whatever_ | _whatever_ |
`hello world` |
hello world |
<code>hello world</code> |
`text` |
__text__ |
<code>__text__</code> |
Pre represents a single block of code, optionally with a language.
This entity starts with ```
(triple backtick), optionally followed with language name and a must be
followed with a line break, and ends with ```
(triple backtick), optionally preceded with a line break.
Code | Result (visual) | Result (as HTML) |
---|---|---|
|
hello |
<pre>hello</pre> |
|
hello |
<pre>hello</pre> |
|
const a = `` |
|
Links are parsed exactly the same as standard markdown (except references are not supported).
Defined like this: [Link text](https://example.com)
.
[
(opening square bracket) inside link text will be treated like a normal character.A markdown-style link can also be used to define a name mention like this: [Name](tg://user?id=1234567)
,
where 1234567
is the ID of the user you want to mention.
Additionally, a markdown-style link can be used to define a custom emoji like this:
[😄](tg://emoji?id=123456)
, where 123456
is ID of the emoji.
Note: It is up to the client to look up user's input entity by ID. 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:
[Name](tg://user?id=1234567&hash=abc
, whereabc
is user's access hash written as a base-16 unsigned integer. Order of the parameters does matter, i.e.tg://user?hash=abc&id=1234567
will not be processed as expected.
Code | Result (visual) | Result (as HTML) |
---|---|---|
[Google](https://google.com) |
<a href="https://google.com">Google</a> |
|
[__Google__](https://google.com) |
<a href="https://google.com"><i>Google</i></a> |
|
[empty link]() |
empty link | empty link |
[empty link] |
[empty link] | [empty link] |
[User](tg://user?id=1234567) |
N/A | N/A |
[😄](tg://emoji?id=123456) |
N/A | N/A |
Quite a powerful feature of this parser is the ability to process overlapping entities. Only inline entities (except code) can be overlapped.
Since inline entities are only defined by their tag, and nesting same entities doesn't make sense, you can think of the tags just as start/end markers, and not in terms of nesting.
Code | Result (visual) | Result (as HTML) |
---|---|---|
**Welcome back, __User__!** |
Welcome back, User! | <b>Welcome back, <i>User</i>!</b> |
**bold __and** italic__ |
bold and italic | <b>bold <i>and</i></b><i> italic</i> |
Being a tagged template literal, md
supports interpolation.
You can interpolate one of the following:
string
- will not be parsed, and appended to plain text as-is
md
as a simple function: md`... ${md('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 md
itself:const bold = md`**bold**`
const text = md`Hello, ${bold}!`
null
, undefined
, false
) - will be ignoredBecause of interpolation, you almost never need to think about escaping anything, since the values are not even parsed as Markdown, and are appended to the output as-is.