Revamp text-formatting page, add info about the new styles
This commit is contained in:
Dan
parent
fa1b66f914
commit
a44c996302
@ -1,40 +1,99 @@
|
||||
Text Formatting
|
||||
===============
|
||||
|
||||
Pyrogram, just like the `Telegram Bot API`_, natively supports basic Markdown and HTML formatting styles for text
|
||||
messages and media captions.
|
||||
.. role:: strike
|
||||
:class: strike
|
||||
|
||||
Markdown style uses the same syntax as Telegram Desktop's and is enabled by default.
|
||||
.. role:: underline
|
||||
:class: underline
|
||||
|
||||
Beside bold, italic, and pre-formatted code, **Pyrogram does also support inline URLs and inline mentions of users**.
|
||||
.. role:: bold-underline
|
||||
:class: bold-underline
|
||||
|
||||
.. role:: strike-italic
|
||||
:class: strike-italic
|
||||
|
||||
Pyrogram uses a custom Markdown dialect for text formatting which adds some unique features that make writing styled
|
||||
texts easier in both Markdown and HTML. You can send sophisticated text messages and media captions using a great
|
||||
variety of decorations that can also be nested in order to combine multiple styles together.
|
||||
|
||||
Basic Styles
|
||||
------------
|
||||
|
||||
When formatting your messages, you can choose between Markdown-style, HTML-style or both (default). The following is a
|
||||
list of the basic styles currently supported by Pyrogram.
|
||||
|
||||
- **bold**
|
||||
- *italic*
|
||||
- :strike:`strike`
|
||||
- :underline:`underline`
|
||||
- `text URL <https://pyrogram.org>`_
|
||||
- `user text mention <https://t.me/haskell>`_
|
||||
- ``inline fixed-width code``
|
||||
- .. code-block:: text
|
||||
|
||||
pre-formatted
|
||||
fixed-width
|
||||
code block
|
||||
|
||||
.. note::
|
||||
|
||||
User text mentions are only guaranteed to work if you have already met the user (in groups or private chats).
|
||||
|
||||
Markdown Style
|
||||
--------------
|
||||
|
||||
To use this mode, pass "markdown" in the *parse_mode* field when using
|
||||
To strictly use this mode, pass "markdown" to the *parse_mode* parameter when using
|
||||
:meth:`~pyrogram.Client.send_message`. Use the following syntax in your message:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
**bold text**
|
||||
**bold**
|
||||
|
||||
__italic text__
|
||||
__italic__
|
||||
|
||||
[inline URL](https://docs.pyrogram.org/)
|
||||
--underline--
|
||||
|
||||
[inline mention of a user](tg://user?id=23122162)
|
||||
~~strike~~
|
||||
|
||||
[text URL](https://docs.pyrogram.org/)
|
||||
|
||||
[text user mention](tg://user?id=23122162)
|
||||
|
||||
`inline fixed-width code`
|
||||
|
||||
```block_language
|
||||
pre-formatted fixed-width code block
|
||||
```
|
||||
pre-formatted
|
||||
fixed-width
|
||||
code block
|
||||
```
|
||||
|
||||
**Example**:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
app.send_message(
|
||||
"haskell",
|
||||
(
|
||||
"**bold**, "
|
||||
"__italic__, "
|
||||
"--underline--, "
|
||||
"~~strikethrough~~, "
|
||||
"[mention](tg://user?id=23122162), "
|
||||
"[URL](https://pyrogram.org), "
|
||||
"`code`, "
|
||||
"```"
|
||||
"for i in range(10):\n"
|
||||
" print(i)"
|
||||
"```"
|
||||
),
|
||||
parse_mode="markdown"
|
||||
)
|
||||
|
||||
HTML Style
|
||||
----------
|
||||
|
||||
To use this mode, pass "html" in the *parse_mode* field when using :meth:`~pyrogram.Client.send_message`.
|
||||
To strictly use this mode, pass "html" to the *parse_mode* parameter when using :meth:`~pyrogram.Client.send_message`.
|
||||
The following tags are currently supported:
|
||||
|
||||
.. code-block:: text
|
||||
@ -43,49 +102,36 @@ The following tags are currently supported:
|
||||
|
||||
<i>italic</i>, <em>italic</em>
|
||||
|
||||
<a href="http://docs.pyrogram.org/">inline URL</a>
|
||||
<u>underline</u>
|
||||
|
||||
<a href="tg://user?id=23122162">inline mention of a user</a>
|
||||
<s>strike</s>, <del>strike</del>, <strike>strike</strike>
|
||||
|
||||
<a href="http://docs.pyrogram.org/">text URL</a>
|
||||
|
||||
<a href="tg://user?id=23122162">inline mention</a>
|
||||
|
||||
<code>inline fixed-width code</code>
|
||||
|
||||
<pre>pre-formatted fixed-width code block</pre>
|
||||
<pre>
|
||||
pre-formatted
|
||||
fixed-width
|
||||
code block
|
||||
</pre>
|
||||
|
||||
.. note:: Mentions are only guaranteed to work if you have already met the user (in groups or private chats).
|
||||
**Example**:
|
||||
|
||||
Examples
|
||||
--------
|
||||
|
||||
- Markdown:
|
||||
|
||||
.. code-block:: python
|
||||
.. code-block:: python
|
||||
|
||||
app.send_message(
|
||||
chat_id="haskell",
|
||||
text=(
|
||||
"**bold**, "
|
||||
"__italic__, "
|
||||
"[mention](tg://user?id=23122162), "
|
||||
"[URL](https://docs.pyrogram.org), "
|
||||
"`code`, "
|
||||
"```"
|
||||
"for i in range(10):\n"
|
||||
" print(i)```"
|
||||
)
|
||||
)
|
||||
|
||||
- HTML:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
app.send_message(
|
||||
chat_id="haskell",
|
||||
text=(
|
||||
"haskell",
|
||||
(
|
||||
"<b>bold</b>, "
|
||||
"<i>italic</i>, "
|
||||
"<u>underline</u>, "
|
||||
"<s>strikethrough</s>, "
|
||||
"<a href=\"tg://user?id=23122162\">mention</a>, "
|
||||
"<a href=\"https://pyrogram.org/\">URL</a>, "
|
||||
"<code>code</code>, "
|
||||
"<code>code</code>\n\n"
|
||||
"<pre>"
|
||||
"for i in range(10):\n"
|
||||
" print(i)"
|
||||
@ -94,4 +140,86 @@ Examples
|
||||
parse_mode="html"
|
||||
)
|
||||
|
||||
.. _Telegram Bot API: https://core.telegram.org/bots/api#formatting-options
|
||||
.. note::
|
||||
|
||||
All ``<``, ``>`` and ``&`` symbols that are not a part of a tag or an HTML entity must be replaced with the
|
||||
corresponding HTML entities (``<`` with ``<``, ``>`` with ``>`` and ``&`` with ``&``). You can use this
|
||||
snippet to quickly escape those characters:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import html
|
||||
|
||||
text = "<my text>"
|
||||
text = html.escape(text)
|
||||
|
||||
print(text)
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
<my text>
|
||||
|
||||
Different Styles
|
||||
----------------
|
||||
|
||||
By default, when ignoring the *parse_mode* parameter, both Markdown and HTML styles are enabled together.
|
||||
This means you can combine together both syntaxes in the same text:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
app.send_message("haskell", "**bold**, <i>italic</i>")
|
||||
|
||||
Result:
|
||||
|
||||
**bold**, *italic*
|
||||
|
||||
If you don't like this behaviour you can always choose to only enable either Markdown or HTML in strict mode by passing
|
||||
"markdown" or "html" as argument to the *parse_mode* parameter.
|
||||
|
||||
.. code-block::
|
||||
|
||||
app.send_message("haskell", "**bold**, <i>italic</i>", parse_mode="markdown")
|
||||
app.send_message("haskell", "**bold**, <i>italic</i>", parse_mode="html")
|
||||
|
||||
Result:
|
||||
|
||||
**bold**, <i>italic</i>
|
||||
|
||||
\*\*bold**, *italic*
|
||||
|
||||
In case you want to completely turn off the style parser, simply pass ``None`` to *parse_mode*. The text will be sent
|
||||
as-is.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
app.send_message("haskell", "**bold**, <i>italic</i>", parse_mode=None)
|
||||
|
||||
Result:
|
||||
|
||||
\*\*bold**, <i>italic</i>
|
||||
|
||||
Nested and Overlapping Entities
|
||||
-------------------------------
|
||||
|
||||
You can also style texts with more than one decoration at once by nesting entities together. For example, you can send
|
||||
a text message with both :bold-underline:`bold and underline` styles, or a text that has both :italic-strike:`italic and
|
||||
strike` styles, and you can still combine both Markdown and HTML together.
|
||||
|
||||
Here there are some example texts you can try sending:
|
||||
|
||||
**Markdown**:
|
||||
|
||||
- ``**bold, --underline--**``
|
||||
- ``**bold __italic --underline ~~striked~~--__**``
|
||||
- ``**bold __and** italic__``
|
||||
|
||||
**HTML**:
|
||||
|
||||
- ``<b>bold, <u>underline</u></b>``
|
||||
- ``<b>bold <i>italic <u>underline <s>striked</s></u></i></b>``
|
||||
- ``<b>bold <i>and</b> italic</i>``
|
||||
|
||||
**Combined**:
|
||||
|
||||
- ``--you can combine <i>HTML</i> with **Markdown**--``
|
||||
- ``**and also <i>overlap** --entities</i> this way--``
|
||||
|
||||
Loading…
Reference in New Issue
Block a user