Skip to content

fix(markdown)!: preserve underscore contexts - #149

Merged
appleboy merged 1 commit into
masterfrom
fix/30-markdown-escaping
Nov 1, 2026
Merged

appleboy merged 1 commit into
masterfrom
fix/30-markdown-escaping

Conversation

@appleboy

@appleboy appleboy commented Nov 1, 2026 •

Copy link
Copy Markdown
Owner

Summary

Messages containing code such as _site or links with underscores were globally rewritten with backslashes, producing visible backslashes or damaged links. Preserve underscores inside complete inline/fenced code, link labels and destinations, and bare HTTP(S) URLs. Keep existing underscore escaping for ordinary text.

Render templates before applying context-aware escaping, so a field can appear in both ordinary text and code without mutating the original field. Add regression coverage and document compatibility behavior.

Compatibility change: custom tpl values now receive ordinary-text underscore escaping, including _italic_; template helpers receive raw fields instead of pre-escaped fields. Use HTML markup for intentional italics and adjust helpers that relied on pre-escaped input. This is not a MarkdownV2 migration or a complete Markdown validator.

Related issues

Architecture / flow

flowchart TD
    Input["Exec: message, file or default message"] --> Render["renderMessages: template.RenderTrim with raw fields"]
    Render --> Decode["html.UnescapeString"]
    Render -->|error| Err["Return error without partial messages"]
    Decode --> Mode{"Format == Markdown?"}
    Mode -->|yes| Escape["escapeMarkdownOne: delimiter index and context scan"]
    Mode -->|no| Ready["renderedMessages"]
    Escape --> Ready
    Ready --> Send["Existing NewMessage / ParseMode / Send"]
    style Render fill:#dff0d8,stroke:#3c763d
    style Escape fill:#dff0d8,stroke:#3c763d
Loading

AI authorship

  • AI was used.
  • Tool: OpenAI Codex.
  • AI-authored files: plugin.go, plugin_test.go, README.md, plan.md.
  • Human line-by-line reviewed: None — not yet reviewed by a human.

Change classification

  • Core change: the shared Markdown preparation path affects both Drone and GitHub Actions notifications.
  • Request at least two human reviewers, including the module owner, with line-by-line review of the scanner and rendering order.

Plan reference

See plan.md for the approved scope, behavior contract, implementation evidence, rollback, and release follow-ups. No CLI, dependency, transport, media, Docker, or workflow changes.

Verification

Setup

Check out fix/30-markdown-escaping in appleboy/drone-telegram and run commands from the repository root. Tested locally with Go 1.26.10 on macOS/arm64, golangci-lint 2.15.0, and standalone gofumpt 0.8.0. CI uses golangci-lint 2.12 and the repository's Linux/Go matrix; remote results remain separate from local evidence.

git fetch origin fix/30-markdown-escaping
git switch fix/30-markdown-escaping
go mod download

The automated checks below need no Telegram credentials. Empty TELEGRAM_TOKEN and TELEGRAM_TO keep credential-gated integration tests skipped. For make fmt-check, ensure gofumpt is on PATH; the local run used a temporary installation:

GOBIN=/tmp/drone-telegram-tools go install mvdan.cc/gofumpt@v0.8.0
PATH="/tmp/drone-telegram-tools:$PATH" make fmt-check

Automated checks

All commands run from the repository root; observed commands were invoked through the local rtk wrapper.

Command Coverage / expected result Status Observed result
env TELEGRAM_TOKEN= TELEGRAM_TO= go test ./... Full offline suite; exit 0 Passed Package passed after lint fixes
env TELEGRAM_TOKEN= TELEGRAM_TO= go test -race ./... Offline suite with race detection; exit 0 Passed Package passed, no races reported
go vet ./... Static checks; exit 0 Passed No issues
golangci-lint run ./... Repository lint/format rules; exit 0 Passed 0 issues on v2.15.0; existing extra-rules deprecation warnings only
PATH="/tmp/drone-telegram-tools:$PATH" make fmt-check Standalone format check; exit 0 Passed Passed with gofumpt 0.8.0
go build -o /tmp/drone-telegram-tools/drone-telegram . Binary compilation; exit 0 Passed Binary built successfully
git diff --check Whitespace validation Passed No errors

Behavioral scenarios

  1. Code/link/URL regression — Passed (payload level). Run go test -run '^TestEscapeMarkdown' -count=1 -v .. Inline code containing _Some text, fenced code, [_Some text](https://example.com/some_path), and a bare URL must remain unchanged; user_name outside these contexts must become user\_name. The initial five regression cases all failed with extra backslashes before the fix and passed afterward. Expanded cases cover escaped delimiters, balanced URL parentheses, Unicode, existing escapes, and unmatched syntax. The large unmatched-delimiter case must complete without truncation or panic.
  2. Template and source compatibility — Passed (payload level). Run go test -run '^TestRenderMessages' -count=1 -v .. A feature_one field must be escaped in ordinary text but preserved in code and a link label, without mutating its source. File/default messages must follow the same rules; HTML and other formats must retain their previous output. The invalid-template case must return an error and no partial messages; a missing message file must retain its load error. Temporary test files are cleaned up by t.TempDir().
  3. Telegram display and destination — Not run. Requires a bot and a disposable test chat. After building the binary, configure PLUGIN_TOKEN and PLUGIN_TO securely for that chat and save only the three message-content lines from the README Markdown example (without the YAML keys) to /tmp/telegram-markdown-example.txt, then run /tmp/drone-telegram-tools/drone-telegram --format Markdown --message.file /tmp/telegram-markdown-example.txt. Expected: code displays _site without an added backslash, ordinary release_name displays literally, and the link destination remains https://example.com/_site. Inspect the URL without needing a successful response from the example website. This sends a real message; delete the test message and unset test credentials afterward. No real messages were sent during this work.

Cleanup

Automated fixtures use temporary directories. The formatter/binary artifacts are under /tmp/drone-telegram-tools; no generated build files or credentials are included in the PR.

Security check

  • No secrets or credentials in the diff.
  • No authentication, permission, or transport changes. Existing error propagation is retained; malformed Markdown remains Telegram's validation responsibility.

Risk and rollback

  • Shared formatting behavior and template helper inputs change; custom templates that depend on pre-escaped fields or unescaped tpl italics need review.
  • Offline payload tests do not prove Telegram's actual rendering of every supported syntax. Complete the disposable-chat check before release.
  • Revert this commit to restore previous behavior; if already released, pin the action to the preceding image. No data migration is involved.

Reviewer guide

  • Read escapeMarkdownOne, markdownDelimiters, markdownURLEnd, and renderMessages carefully: delimiter pairing, backslash parity, URL boundaries, malformed-input fallback, and rendering order are the main risks.
  • Compare tests against the documented compatibility contract. The formatter also adjusted the closing layout of the existing template test.
  • Confirm manual Telegram rendering before release, then publish drone-telegram and update the action image separately.

- Preserve underscores in code, links, and HTTP URLs
- Escape rendered messages without mutating template fields
- Cover formatting boundaries, templates, and error paths

BREAKING CHANGE: Custom tpl underscores are now escaped in ordinary Markdown text, and template helpers receive raw fields. Use HTML formatting for intentional italics and update helpers that relied on pre-escaped fields.

Related to appleboy/telegram-action#30
Copilot AI balanced review requested due to automatic review settings November 1, 2026 05:41
@appleboy
appleboy merged commit 9af0216 into master Nov 1, 2026
13 checks passed
@appleboy
appleboy deleted the fix/30-markdown-escaping branch November 1, 2026 05:43

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

URL preservation fails for mixed-case schemes and bracketed IPv6 hosts, while backslash handling breaks inline-code delimiter pairing and introduces visible escapes.

3 open issues
What changed in this PR

This PR updates shared Markdown message preparation for Drone and GitHub Actions notifications to preserve underscores in code, links, and bare HTTP(S) URLs while retaining ordinary-text escaping.

Changes:

  • Adds context-aware underscore handling after template rendering, without mutating source fields.
  • Adds regression coverage for formatting contexts, templates, message sources, and errors.
  • Documents compatibility changes and pending Telegram rendering verification.
File Description
README.md Explains Markdown escaping, template compatibility, and the HTML alternative.
plugin.go Adds context scanning and centralizes render-before-escape message preparation.
plugin_test.go Adds context, rendering, source-preservation, and error regression tests.
plan.md Records the behavior contract, verification evidence, and release follow-ups.

Review effort: Balanced

Comment thread plugin.go
Comment on lines +163 to +166
case 'h':
if strings.HasPrefix(str[i:], "https://") || strings.HasPrefix(str[i:], "http://") {
end = markdownURLEnd(str, i)
}
Comment thread plugin.go
Comment on lines +198 to +199
case '\\':
i++
Comment thread plugin.go
i := start
for i < len(str) {
r, size := utf8.DecodeRuneInString(str[i:])
if unicode.IsSpace(r) || unicode.IsControl(r) || strings.ContainsRune("`<>[]", r) {
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants

⌂ 换网址