Skip to content

Migrate from Markdown v1 to HTML parse mode#26

Merged
RichardAtCT merged 2 commits intomainfrom
fix/markdown-handling
Feb 13, 2026
Merged

Migrate from Markdown v1 to HTML parse mode#26
RichardAtCT merged 2 commits intomainfrom
fix/markdown-handling

Conversation

@RichardAtCT
Copy link
Copy Markdown
Owner

@RichardAtCT RichardAtCT commented Feb 13, 2026

Summary

  • Replace fragile Markdown v1 parsing with HTML parse mode — Telegram's Markdown v1 parser frequently chokes on Claude's output (underscores in identifiers, asterisks, brackets). HTML only requires escaping 3 characters (<, >, &), making it far more robust.
  • Add src/bot/utils/html_format.py with escape_html() and markdown_to_telegram_html(), replacing 3 inconsistent _escape_markdown functions scattered across handlers.
  • Fix middleware bug where **bold** was sent without parse_mode, causing users to see literal asterisks in auth, rate limit, and security messages.
  • Add HTML fallback safety net — if Telegram rejects malformed HTML, messages are retried as plain text to prevent silent failures.

Changes

  • 15 files changed across handlers, orchestrator, middleware, features, events, notifications, and tests
  • All 271 tests pass, black/isort/flake8 clean

Test plan

  • make test — all 271 tests pass
  • make lint — black, isort, flake8 clean (mypy errors all pre-existing)
  • Manual test: send messages with underscores, asterisks, angle brackets, and code blocks through the bot to confirm proper rendering

@RichardAtCT
Migrate from Markdown v1 to HTML parse mode
c765e37 
Telegram's Markdown v1 parser is fragile with Claude's output — underscores
in identifiers, asterisks, and brackets frequently cause parse failures.
Switching to parse_mode="HTML" is more robust since only 3 characters need
escaping (<, >, &) vs the many ambiguous Markdown v1 metacharacters.

- Add src/bot/utils/html_format.py with escape_html() and
  markdown_to_telegram_html() replacing 3 inconsistent _escape_markdown fns
- Update all handlers, orchestrator, middleware, and features to use HTML
- Fix middleware bug where **bold** was sent without parse_mode
- Add HTML send fallback: retry as plain text if Telegram rejects HTML
- Update all tests for HTML assertions
@RichardAtCT
Copy link
Copy Markdown
Owner Author

RichardAtCT commented Feb 13, 2026

PR Review
Reviewed head: c765e37ccf4db72639c1b1b4700cfa238c7cdf8f

Summary

  • Strong direction overall: moving from Markdown v1 to HTML parse mode is a sensible reliability improvement for Claude output.
  • The new shared formatter (html_format.py) and broad middleware/handler parse_mode consistency fixes are good cleanup.

What looks good

  • Centralizing escaping/conversion instead of 3+ ad-hoc escape helpers reduces future regressions.
  • Adding HTML-send fallback to plain text in message/orchestrator paths is a practical safety net.
  • Test coverage expansion in tests/unit/test_bot/test_formatting.py is helpful and targeted.

Issues / questions

  1. [Blocker] src/bot/handlers/command.py (start_command) — user.first_name is interpolated directly into an HTML-parsed message without escaping:
    • Current: f"👋 Welcome to Claude Code Telegram Bot, {user.first_name}!\n\n" with parse_mode="HTML"
    • If the name contains <, >, or &, Telegram HTML parsing can fail or mis-render.
    • Please wrap this with escape_html(user.first_name) (same pattern used in orchestrator).

Suggested tests (if needed)

  • Add a unit test for /start where first_name includes HTML chars (e.g. A<B>&C) and assert escaped output is sent with parse_mode="HTML".

Verdict

  • ⚠️ Merge after fixes

@RichardAtCT
Escape user.first_name in start_command HTML output
9d85b87 
Wraps user.first_name with escape_html() to prevent parse failures
when names contain <, >, or & characters.
@RichardAtCT RichardAtCT merged commit 61d1712 into main Feb 13, 2026
1 check passed
@RichardAtCT RichardAtCT deleted the fix/markdown-handling branch February 14, 2026 11:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@RichardAtCT