Proper use of markdown

As most of you already know, bots have the ability to format text.

There are various way you can format a message:

• Bold -> *bold*
• Italic -> _Italic_
• Fixedsys (that can't be used on a Telegraph) -> `fixedsys`
• Inline links -> [inline links](https://telegram.me/groupbutler_bot)

As you can see from the examples above, to format your text you must use some special characters, that Telegram uses to understand which words should be in bold, which must be in italic and so on.

Anyway, a formatted text must follow some rules, or Telegram won't let the bot send the message.

So in this telegraph you will find some common errors you could do while formatting your texts, along with some possible solutions to avoid to get the "wrong markdown" message.

You always have to close a string opened with a special character

If you are going to write a message and you want to format a single word or a sentence in bold (for example), you always have to insert the closing *, or Telegram will answer the bot "no, you can't send this because you're breaking the markdown", when it tries to send the message.

So, a general rule is: markdown symbols (*, _, `) must be present in even number in your message. Odd number of *, _ or ` will result in a wrong markdown message.

But what if you have to write a special symbol that is not intended to format a text?

Sometimes we have to use in our messages a * or a _ that must not be intended as markdown symbol. In this case, we have to tell Telegram to ignore it by escaping the symbol. For example, usernames or links often contains an underscore _.

But how do we escape a markdown symbol? Simple, by placing a backslash before it.

• * becomes \*
• _ becomes \_
• ' becomes \'

The backslash will tell Telegram that we don't want that symbol to be interpreted as a markdown symbol.

Some examples:

• this is a normal start *, plus some bold text <- this is a normal star \*, plus some *bold text*
• @user_name, and italic text <- @user\_name, and _italic text_

Important exception: we can't escape a * in the middle of a bold sentence. This applies to _ and ` too.

Examples:

A bot can't send this message: *This is a \* normal sentence in bold*

As you can see, in the above sentence we are trying to escape (with the backslash, \) a star (*) in the middle of a bold sentence. This is something that Telegram doesn't allow.

So please check that you are not doing this error. Also, remember that user names could contain markdown symbols, so avoid to wrap placeholders such as $name or $surname within * and _, or the bot won't be able to send the message.

Inline links

Inline links are cool, and strongly suggested because they allow you to avoid to escape underscores that appear in your links.

That's how an inline link looks like: Telegram site -> [Telegram site](https://telegram.org/)

Square brackets must contain the clickable blue word that will appear in the message, normal brackets are for the actual link (you don't have to escape the special characters that may appear in a link).

But inline links bring some problems with square brackets, too.

Every time Telegram will face a pair of square brackets, it will expect to find a pair of normal brackets right after the closing "]". If it doesn't find it, or the normal brackets don't contain a valid url, a markdown error is raised.

Square brackets can be escaped too: just put our beloved backslash before them.

Example:

Not correct: this text [is inserted in a pair of square brackets that are not used for an inline link]

Correct: this text \[is correct] (there is a backslash before the square bracket, because we are not usign them for a link)

Remember: you can't place square brackets in the middle of other square brackets, with inline links.

Note about $rules: this placeholder is the only non-url word you can insert in the middle of two (), because it's replaced with a link that redirects to the bot itself. More info here.