Skip to content
asterfield-devPublic

About

Minimal Telegram bot that renders Rich Markdown natively with Telegram Bot API 10.1. Built in Go with PostgreSQL-backed audit and statistics.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

makeitMD

Send Markdown. Get native Telegram rich text.
A deliberately small Go bot built directly on Telegram Bot API 10.1.

latest version stable version Go version Apache-2.0 license Telegram bot

Quick Start · Usage · How It Works · Operations · Configuration


The Idea

Telegram Bot API 10.1 can render structured Rich Markdown natively. makeitMD keeps the product boundary as small as possible: send source text in a private chat and receive Telegram's native rendering immediately.

Principle makeitMD approach
Exact input Preserves source; restores formatting consumed by Telegram clients
Native rendering Uses Telegram sendRichMessage, not a custom parser
Minimal interaction /start only, one panel: two tabs and the language, no settings
Private operations Statistics and source audit stay operator-only
Shared integration Uses the family’s small github.com/asterfield-dev/tg HTTP client

Result: one text message or text file in, one native rich message out.

Status

Channel Version Meaning
Stable tag v0.1.2 Latest stable version recorded in this repository
Development dev File input and clearer formula help, not released

The running production version must be checked through /healthz or About; this table is not a live deployment check.

Quick Start

You need Go 1.26.10+, Docker, a Telegram token from BotFather, and access to the Asterfield shared core-postgres database.

cp .env.example .env
$EDITOR .env
docker compose up --build

Before the first start, apply core/migrations/003_makeitmd.sql, provision the makeitmd_core password, and ensure the external Docker network core_net exists.

Using makeitMD

  1. Open @makeitMD_bot.
  2. Send /start.
  3. Send Markdown source text, or attach a UTF-8 text file.
  4. Receive the native Telegram Rich Markdown message.

The greeting is intentionally short:

Send me Markdown as a message or a text file. I’ll render it.

Files such as .md, .txt, .markdown, .mdown, .csv, .json, .tex, and extensionless text are accepted by content, regardless of the supplied MIME type. The limit is 128 KiB (131,072 bytes), including an optional UTF-8 BOM. The file contents are rendered as Rich Markdown, not converted from another document format. PDF, Word, archives, invalid UTF-8, and binary data are rejected. Captions are ignored. Each file is one conversion and is never joined to a nearby text message or another file.

An ordinary paste of a chatbot's answer gives Telegram the clipboard's HTML, and the client keeps only what a plain message can hold: headings, lists, tables and LaTeX backslashes are gone before makeitMD receives the text. Paste without formatting (⌘⇧V, Ctrl+Shift+V) or send a file instead. When a long message arrives with a quote or text link and no heading, table or bullet line left, the reply is followed by that advice.

A client can also send a paste as a rich message (Bot API 10.1): formatted blocks with no text and no Markdown source. makeitMD does not render those; it answers with the same advice and stores nothing. Its log records only how many blocks of each type arrived.

Downloads use the shared Telegram client, have a 15-second budget including getFile, and are removed from a private temporary directory after processing. Accepted source and original document metadata follow the existing conversion retention policy. Rejected or unsuccessfully downloaded files do not create a conversion row. A download failure asks the sender to resend the file.

/start also opens the panel: How it works, About — the running version, the rendering the bot uses, the repository, the licence and the admin — and Language. Back returns to the greeting, and every screen edits the same message rather than adding another one. There is nothing else to configure, so there is no settings screen.

The panel speaks the sixteen languages the Asterfield bots share. It follows the language your Telegram client reports until you pick one, and the language you pick is stored once for the whole family: the other bots answer in it too. Follow Telegram on that screen hands the decision back to your client.

Everything else the bot says is a rendered message. In a group makeitMD renders nothing: /start there is registered as an ephemeral command, so the answer — a link back to the private chat — is visible only to the person who sent it.

Rich Markdown supports headings, nested styles, lists, task lists, tables, quotes, code blocks, details, links, formulas, and other structured content. Telegram currently limits one rich message to 32,768 UTF-8 characters of rendered text, including formula source and custom emoji alternative text. Source bytes and rendered characters are different limits. Telegram also limits block count, nesting, media and table width. Oversized documents are not truncated or split automatically, because splitting could break tables, code or formulas.

Formulas

Telegram Rich Markdown supports inline $x^2 + y^2$, block $$E=mc^2$$, and fenced math blocks:

Inline: $\frac{a}{b}$

$$E=mc^2$$

```math
\int_0^1 x^2\,dx = \frac{1}{3}
```

The formula source goes to Telegram unchanged. Telegram’s documented syntax is not a promise of full KaTeX or a complete TeX document engine.

\(...\) and \[...\], the delimiters ChatGPT writes, are the first rewrite: Markdown reads \( as an escaped parenthesis, so Telegram would show (x^2) instead of a formula. Outside code they become $...$ and $$...$$. An escaped backslash (\\() is left alone, and \[...\] is converted only when it stands on its own lines or contains LaTeX syntax, so \[1\] stays a bracketed reference. ChatGPT’s copy button escapes the Markdown once more (\\[ 1\\,000 \\]); these doubled delimiters are formulas too, with the content unescaped, but only when one of them contains LaTeX syntax, so a path like C:\\(x86\\) stays text.

The second rewrite applies to pastes only, where the source has no $, \( or \[ at all. Chatbot apps on phones copy a display formula as bare LaTeX: a line A=P\cdot\frac{r}{1-(1+r)^{-n}}, or a code block with no language. Such a line or block becomes $$...$$ when it reads as a formula: a LaTeX command next to math, or a sub/superscript with a relation, and no word of three or more letters once commands and braced arguments are removed. A \begin{...} split over lines and consecutive formula lines become one formula. Prose with an inline \lambda, code, links and paths stay text. Formulas a phone app deleted while copying cannot be recovered. Putting $...$ inside ordinary inline code or a non-math code block makes it code, not a formula. Receiving clients must support rich messages.

See Telegram’s Rich Markdown syntax and limits and file download contract.

How It Works

Telegram getUpdates
        |
        v
core.touch identity/presence
        |
        v
store exact source as received
        |
        v
sendRichMessage(markdown: exact source)
        |
        +--> sent   -> lifetime statistics
        +--> failed -> short syntax error

The durable Telegram offset advances only after handling an update. Replayed updates do not resend conversions already marked sent.

Shared Core Database

Global Telegram identity and presence live in core.person and core.presence. Private makeitMD data lives in the isolated makeitmd schema:

  • makeitmd.conversions — exact decoded source, raw input message and entities, every outbound Markdown/result attempt, final Telegram result, delivery state, character count, and byte count.
  • makeitmd.user_stats — lifetime per-user conversion totals independent of raw-text retention.
  • makeitmd.runtime_state — durable Telegram update offset.
  • makeitmd.schema_migrations — applied domain migration ledger.

Raw sent and failed conversions expire after 90 days by default. Unresolved received rows remain available for recovery. No statistics are shown to users.

Operations

  • GET /healthz checks PostgreSQL and Telegram polling freshness and returns version, commit, build date, and pending/failed conversion counts.
  • GET /metrics exposes private-data-free Prometheus counters.
  • Docker marks the container unhealthy when /healthz fails.
  • Telegram GET requests retry transport, 429, and 5xx failures with jitter.
  • POST requests retry only when Telegram explicitly returns retry_after, avoiding unsafe duplicate sends after an ambiguous transport failure.
  • Transport errors are sanitized before logging so the bot token cannot appear through an embedded Bot API URL.

Configuration

Variable Required Default Purpose
TELEGRAM_BOT_TOKEN yes — Telegram Bot API token
DATABASE_URL yes — makeitmd_core connection to shared core-postgres
AUTO_MIGRATE no true Apply makeitMD migrations on startup
MIGRATIONS_DIR no ./migrations SQL migration directory
HTTP_ADDR no :8080 Internal health and metrics listener
CONVERSION_RETENTION no 2160h Retention for terminal raw conversion rows
LOG_LEVEL no info Reserved log level
BUILD_VERSION no dev Version stamped into health and logs
BUILD_COMMIT no none Source revision
BUILD_DATE no unknown UTC build timestamp

Production

deploy/ws04/compose.yaml is the production stack. It pulls the image the release workflow published to GHCR and never builds one:

# in the stack directory, alongside .env
MAKEITMD_IMAGE=ghcr.io/asterfield-dev/makeitmd@sha256:<digest> docker compose up -d

Pin MAKEITMD_IMAGE by digest rather than tag. A digest names one exact build, so a rollback is a one-line change with nothing to rebuild, and docker inspect on the running container answers which commit it came from. BUILD_VERSION / BUILD_COMMIT / BUILD_DATE are baked in by the release workflow; they only need setting for a local build.

Development

go mod verify
go test -race ./...
go vet ./...
govulncheck ./...
docker compose config
docker build -t makeitmd:local .

CI repeats module verification, build, race tests, vet, vulnerability scanning, Docker build, and Compose validation. See versioning, release process, and the full changelog.

License

Apache License 2.0. See LICENSE and NOTICE.

About

Minimal Telegram bot that renders Rich Markdown natively with Telegram Bot API 10.1. Built in Go with PostgreSQL-backed audit and statistics.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages