chore: moved docs inside the main repo

Co-authored-by: Kamilla 'ova <me@kamillaova.dev>
Co-authored-by: Alina Chebakova <chebakov05@gmail.com>
Co-authored-by: Kravets <57632712+kravetsone@users.noreply.github.com>
Co-authored-by: starkow <hello@starkow.dev>
Co-authored-by: sireneva <150665887+sireneva@users.noreply.github.com>

docs/guide/topics/parse-modes.md

@@ -0,0 +1,107 @@
+# Parse modes
+
+You may be familiar with parse modes from the Bot API. Indeed,
+the idea is pretty much the same - parse mode defines the syntax to use
+for formatting entities in messages. 
+
+However, there's a major difference – in mtcute, the client doesn't know anything about
+how the parse modes are implemented. Instead, it just accepts an object containing
+the `text` and `entities` fields, and sends it to the server:
+
+```ts
+await tg.sendText('self', {
+    text: 'Hi, User!',
+    entities: [
+        { _: 'messageEntityBold', offset: 4, length: 4 }
+    ]
+})
+```
+
+Of course, passing this object manually is not very convenient, 
+so mtcute provides a set of *parsers* that can be used to convert
+a string with entities to this structure.
+
+For convenience, mtcute itself provides two parsers – for Markdown and HTML.
+They are both implemented as separate packages, and they themselves are tagged template literals,
+which makes it very easy to interpolate variables into the message.
+
+
+## Markdown
+
+Markdown parser is implemented in `@mtcute/markdown-parser` package:
+
+```ts
+import { md } from '@mtcute/markdown-parser'
+
+dp.onNewMessage(async (msg) => {
+    await msg.answerText(md`Hello, **${msg.sender.username}**`)
+})
+```
+
+**Note**: the syntax used by this parser is **not** compatible
+with Bot API's Markdown or MarkdownV2 syntax.
+See [documentation](https://ref.mtcute.dev/modules/_mtcute_markdown_parser.html)
+to learn about the syntax.
+
+## HTML
+
+HTML parser is implemented in `@mtcute/html-parser` package:
+
+```ts
+import { html } from '@mtcute/html-parser'
+
+dp.onNewMessage(async (msg) => {
+    await msg.answerText(html`Hello, <b>${msg.sender.username}</b>`)
+})
+```
+
+**Note**: the syntax used by this parser is **not** 
+compatible with Bot API's HTML syntax. 
+See [documentation](https://ref.mtcute.dev/modules/_mtcute_html_parser.html)
+to learn about the syntax.
+
+## Interpolation
+
+Both parsers support interpolation of variables into the message, 
+as can be seen in the examples above.
+
+Both parsers support the following types of interpolation:
+- `string` - **will not** be parsed, and appended to plain text as-is
+- `number` - will be converted to string and appended to plain text as-is
+- `TextWithEntities` or `MessageEntity` - will add the text and its entities to the output. 
+  This is the type returned by `md` and `html` themselves, so you can even mix and match them:
+  ```ts
+    const greeting = (user) => html`<i>${user.displayName}</i>`
+    const text = md`**Hello**, ${user}!`
+  ```
+- falsy value (i.e. `null`, `undefined`, `false`) - will be ignored
+
+### Unsafe interpolation
+
+In some cases, you may already have a string with entities, and want to parse it to entities. 
+
+In this case, you can use the method as a function:
+
+```ts
+const text = 'Hello, **User**!'
+
+await tg.sendText('self', md(text))
+// or even
+await tg.sendText('self', md`${md(text)} What's new?`)
+```
+
+## Un-parsing
+
+Both HTML and Markdown parsers also provide an `unparse` method,
+which can be used to convert the message back to the original text:
+
+```ts
+import { html } from '@mtcute/html-parser'
+
+const msg = await tg.sendText('Hi, <b>User</b>!', { parseMode: 'html' })
+
+console.log(msg.text)
+// Hi, User!
+console.log(html.unparse())
+// Hi, <b>User</b>!
+```