Send Markdown. Get native Telegram rich text.
A deliberately small Go bot built directly on Telegram Bot API 10.1.
Quick Start · Usage · How It Works · Operations · Configuration
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.
| 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.
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 --buildBefore the first start, apply core/migrations/003_makeitmd.sql, provision the
makeitmd_core password, and ensure the external Docker network core_net
exists.
- Open @makeitMD_bot.
- Send
/start. - Send Markdown source text, or attach a UTF-8 text file.
- 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.
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.
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.
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.
GET /healthzchecks PostgreSQL and Telegram polling freshness and returns version, commit, build date, and pending/failed conversion counts.GET /metricsexposes private-data-free Prometheus counters.- Docker marks the container unhealthy when
/healthzfails. - 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.
| 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 |
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 -dPin 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.
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.