https://github.com/tishka17/sulguk
HTML to telegram entities converter
https://github.com/tishka17/sulguk
html sulguk telegram
Last synced: 3 months ago
JSON representation
HTML to telegram entities converter
- Host: GitHub
- URL: https://github.com/tishka17/sulguk
- Owner: Tishka17
- License: apache-2.0
- Created: 2023-07-22T20:17:11.000Z (almost 3 years ago)
- Default Branch: develop
- Last Pushed: 2025-12-29T16:53:17.000Z (7 months ago)
- Last Synced: 2026-01-01T21:41:15.240Z (7 months ago)
- Topics: html, sulguk, telegram
- Language: Python
- Homepage:
- Size: 160 KB
- Stars: 113
- Watchers: 2
- Forks: 14
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Sulguk - HTML to telegram entities converter
================================================
[](https://badge.fury.io/py/sulguk)
[](https://pypistats.org/packages/sulguk)
[](https://github.com/Tishka17/sulguk/blob/master/LICENSE)
Need to deliver formatted content to your bot clients?
Having a hangover after trying to fit HTML into telegram?
Beautifulsoup is too complicated and not helping with messages?
Try `sulguk` (술국, a hangover
soup) - [delivered since 1800s](https://en.wikipedia.org/wiki/Food_delivery).
## Problem
Telegram supports `parse_mode="html"`, but:
* Telegram processes spaces and new lines incorrectly. So we cannot format HTML source for more readability.
* Amount of supported tags is very low
* It does not ignore additional attributes in supported tags.
Let's imagine we have HTML like this:
```html
This is a demo of Sulguk
Underlined
Italic
Bold
```
This is how it is rendered in browser (expected behavior):
But this is how it is rendered in Telegram with `parse_mode="html"`:
To solve this we can convert HTML to telegram entities with `sulguk`. So that's how it looks now:
## Example
1. Create your nice HTML:
```html
- some item
- other item
Some text in a paragraph
```
2. Convert it into text and entities
```python
result = transform_html(raw_html)
```
3. Send it to telegram.
Depending on your library you may need to convert entities from dict into
proper type
```python
await bot.send_message(
chat_id=CHAT_ID,
text=result.text,
entities=result.entities,
)
```
## Example for aiogram users
1. Add `SulgukMiddleware` to your bot
```python
from sulguk import AiogramSulgukMiddleware
bot.session.middleware(AiogramSulgukMiddleware())
```
2. Create your nice HTML:
```html
- some item
- other item
Some text in a paragraph
```
3. Send it using `sulguk` as a `parse_mode`:
```python
from sulguk import SULGUK_PARSE_MODE
await bot.send_message(
chat_id=CHAT_ID,
text=raw_html,
parse_mode=SULGUK_PARSE_MODE,
)
```
## Supported tags:
For all supported tags unknown attributes are ignored as well as unknown classes.
Unsupported tags are raising an error.
**Note:** In standard Telegram HTML you can set a preformatted text language nesting `` in `` tag. This works when it is an only child. But any additional symbol outside of `` breaks it.
The same behavior is supported in sulguk. Otherwise, you can set the language on `` tag itself.
#### Additional tags:
* `
` - new line
* `
` - horizontal line
* `` - word break opportunity
* `
- ` - unordered list
- ` - list item, with optional `value` attribute to change number. Nested lists have
indentation
* `` - a block (not inline) element
* `` - a paragraph, emphasized with empty lines
* `` - a quoted text
* `` - a block quote. Like a paragraph with indentation
* `` - a block quote with expandable
* ``-`
` - text headers, styled using available telegram options
* `` - contents is shown as not scripting is supported
* ``, `` - italic
* ``, `` are rendered using emoji (🟩🟩🟩🟨⬜️⬜️)
* ``, `` - preformatted text
* `` - as a link with picture emoji before. `alt` text is used if provided.
* `` - as italic text
* `` - as symbols ✅⬜️(checkbox), 🔘⚪️(radio) or `_______`/value in other cases#### Tags which are treated as block elements (like `
`):
``, ``, ``, ``, ``#### Tags which are treated as inline elements (like ``):
``, ``, ``, ``, `#### Tags which contents is ignored:
``, ``, ``, ``, `<style>`, `<template>`, `<title>`
## Command line utility for channel management
1. Install with addons
```shell
pip install 'sulguk[cli]'
```2. Set environment variable `BOT_TOKEN`
```shell
export BOT_TOKEN="your telegram token"
```3. Send HTML file as a message to your channel. Additional files will be sent as comments to the first one. You can provide a channel name or a public link
```shell
sulguk send @chat_id file.html
```4. If you want to, edit using the link from shell or from your tg client. Edition of comments is supported as well.
```shell
sulguk edit 'https://t.me/channel/1?comment=42' file.html
```
* `
- ` - ordered list with optional attributes
* `reversed` - to reverse numbers order
* `type` (`1`/`a`/`A`/`i`/`I`) - to set numbering style
* `start` - to set starting number
* `