# `ExGram.Markdown`
[🔗](https://github.com/rockneurotiko/ex_gram/blob/0.64.0/lib/ex_gram/markdown.ex#L2)

Converts CommonMark/GFM Markdown into a `{plain_text, [MessageEntity]}` tuple
for the Telegram Bot API.

Uses [MDEx](https://hexdocs.pm/mdex) (backed by Rust's `comrak`) for spec-compliant
parsing, then walks the AST to produce plain text annotated with `ExGram.Model.MessageEntity`
structs whose `offset` and `length` fields are measured in UTF-16 code units
(as required by Telegram).

## Options

  * `:skip_blockquotes` - when `true`, blockquote nodes are rendered as
    indented plain text instead of a `blockquote` entity. Useful when the
    output will itself be wrapped in an expandable blockquote, since Telegram
    forbids nested blockquotes.

## Fallback

If [MDEx](https://hexdocs.pm/mdex) fails to parse, the raw markdown is returned
as plain text with no entities.

## Example

    iex> ExGram.Markdown.to_entities("**bold** and *italic*")
    {"bold and italic",
     [
       %ExGram.Model.MessageEntity{type: "bold", offset: 0, length: 4},
       %ExGram.Model.MessageEntity{type: "italic", offset: 9, length: 6}
     ]}

# `from_entities`

```elixir
@spec from_entities(ExGram.Dsl.MessageEntityBuilder.t(), :markdown | :markdown_v2) ::
  String.t()
```

Converts a `t:ExGram.Dsl.MessageEntityBuilder.t/0` back into a markdown string.

> #### Warning {: .warning}
>
> The conversion from markdown <-> entities is not 1 on 1, since entities is a limited
> subset of markdown.

## Formats

  * `:markdown` - CommonMark output (via [MDEx](https://hexdocs.pm/mdex) AST)
  * `:markdown_v2` - Telegram MarkdownV2 output with proper escaping

## Example

    iex> alias ExGram.Model.MessageEntity
    iex> entities = [%MessageEntity{type: "bold", offset: 0, length: 4}]
    iex> ExGram.Markdown.from_entities({"bold text", entities}, :markdown)
    "**bold** text"
    iex> ExGram.Markdown.from_entities({"bold text", entities}, :markdown_v2)
    "*bold* text"

# `to_entities`

```elixir
@spec to_entities(
  String.t(),
  keyword()
) :: ExGram.Dsl.MessageEntityBuilder.t()
```

Converts a Markdown string into a `t:ExGram.Dsl.MessageEntityBuilder.t/0` ready to be used.

---

*Consult [api-reference.md](api-reference.md) for complete listing*