fix(telegram): preserve markdown paragraph spacing

Purpose of the change:
- Preserve markdown paragraph spacing when converting messages for Telegram Markdown and HTML targets.

How behavior was before:
- Paragraph blocks and hard line breaks were both normalized through single-line break handling.
- The markdown renderer's newline after generated <br> nodes could combine with explicit block breaks.

Why that was a problem:
- Blank lines appeared to move in Telegram messages, matching the spacing regression reported in #48.
- Consecutive metadata lines could gain extra blank lines while real paragraph gaps disappeared.

What the new change accomplishes:
- Keeps paragraph boundaries as paragraph breaks while preserving single hard line breaks as one newline.
- Adds regression coverage for the exact issue sample across Telegram Markdown v1, MarkdownV2, and HTML output.

How it works:
- Introduces paragraph-aware block handling for Telegram renderers.
- Trims parser-inserted text-node newlines that immediately follow <br> elements.

Author: elibosley

internal/notify/telegram_format_convert.go

@@ -22,6 +22,18 @@ var telegramHTMLBlockTags = map[string]struct{}{
 	"pre":        {},
 }
 
+var telegramHTMLParagraphTags = map[string]struct{}{
+	"blockquote": {},
+	"div":        {},
+	"h1":         {},
+	"h2":         {},
+	"h3":         {},
+	"h4":         {},
+	"h5":         {},
+	"h6":         {},
+	"p":          {},
+}
+
 func convertTelegramMessageFormat(content, inputFormat, outputFormat, markdownVersion string) (string, error) {
 	input := normalizeNotifyFormat(inputFormat)
 	output := normalizeNotifyFormat(outputFormat)
@@ -81,10 +93,11 @@ func telegramHTMLFromHTML(content string) string {
 
 func renderTelegramHTMLNode(out *strings.Builder, node *nethtml.Node, inCode bool) {
 	if node.Type == nethtml.TextNode {
-		if !inCode && strings.TrimSpace(node.Data) == "" && strings.ContainsAny(node.Data, "\r\n") {
+		data := telegramTextNodeData(node)
+		if !inCode && strings.TrimSpace(data) == "" && strings.ContainsAny(data, "\r\n") {
 			return
 		}
-		out.WriteString(html.EscapeString(node.Data))
+		out.WriteString(html.EscapeString(data))
 		return
 	}
 	if node.Type != nethtml.ElementNode {
@@ -93,8 +106,12 @@ func renderTelegramHTMLNode(out *strings.Builder, node *nethtml.Node, inCode boo
 	}
 
 	tag := strings.ToLower(node.Data)
-	if _, ok := telegramHTMLBlockTags[tag]; ok && out.Len() > 0 {
-		ensureLineBreak(out)
+	if out.Len() > 0 {
+		if _, ok := telegramHTMLParagraphTags[tag]; ok {
+			ensureParagraphBreak(out)
+		} else if _, ok := telegramHTMLBlockTags[tag]; ok {
+			ensureLineBreak(out)
+		}
 	}
 
 	switch tag {
@@ -150,7 +167,9 @@ func renderTelegramHTMLNode(out *strings.Builder, node *nethtml.Node, inCode boo
 		renderTelegramHTMLChildren(out, node, inCode)
 	}
 
-	if _, ok := telegramHTMLBlockTags[tag]; ok {
+	if _, ok := telegramHTMLParagraphTags[tag]; ok {
+		ensureParagraphBreak(out)
+	} else if _, ok := telegramHTMLBlockTags[tag]; ok {
 		ensureLineBreak(out)
 	}
 }
@@ -177,14 +196,15 @@ func telegramMarkdownFromHTML(content, markdownMode string) string {
 
 func renderTelegramMarkdownNode(out *strings.Builder, node *nethtml.Node, markdownMode string, inCode bool) {
 	if node.Type == nethtml.TextNode {
+		data := telegramTextNodeData(node)
 		if inCode {
-			out.WriteString(escapeTelegramMarkdownCodeText(node.Data, markdownMode))
+			out.WriteString(escapeTelegramMarkdownCodeText(data, markdownMode))
 			return
 		}
-		if strings.TrimSpace(node.Data) == "" && strings.ContainsAny(node.Data, "\r\n") {
+		if strings.TrimSpace(data) == "" && strings.ContainsAny(data, "\r\n") {
 			return
 		}
-		out.WriteString(escapeTelegramMarkdownText(node.Data, markdownMode))
+		out.WriteString(escapeTelegramMarkdownText(data, markdownMode))
 		return
 	}
 	if node.Type != nethtml.ElementNode {
@@ -193,8 +213,12 @@ func renderTelegramMarkdownNode(out *strings.Builder, node *nethtml.Node, markdo
 	}
 
 	tag := strings.ToLower(node.Data)
-	if _, ok := telegramHTMLBlockTags[tag]; ok && out.Len() > 0 {
-		ensureLineBreak(out)
+	if out.Len() > 0 {
+		if _, ok := telegramHTMLParagraphTags[tag]; ok {
+			ensureParagraphBreak(out)
+		} else if _, ok := telegramHTMLBlockTags[tag]; ok {
+			ensureLineBreak(out)
+		}
 	}
 
 	switch tag {
@@ -254,7 +278,9 @@ func renderTelegramMarkdownNode(out *strings.Builder, node *nethtml.Node, markdo
 		renderTelegramMarkdownChildren(out, node, markdownMode, inCode)
 	}
 
-	if _, ok := telegramHTMLBlockTags[tag]; ok {
+	if _, ok := telegramHTMLParagraphTags[tag]; ok {
+		ensureParagraphBreak(out)
+	} else if _, ok := telegramHTMLBlockTags[tag]; ok {
 		ensureLineBreak(out)
 	}
 }
@@ -332,6 +358,61 @@ func htmlAttr(node *nethtml.Node, key string) string {
 	return ""
 }
 
+// telegramTextNodeData returns node text while trimming leading CR/LF only after
+// a preceding br element, as reported by previousElementTag, to compensate for
+// markdown parsers that emit a formatting newline after <br>. Other whitespace
+// is preserved in non-br contexts.
+func telegramTextNodeData(node *nethtml.Node) string {
+	if node == nil {
+		return ""
+	}
+	data := node.Data
+	if previousElementTag(node) == "br" {
+		data = strings.TrimLeft(data, "\r\n")
+	}
+	return data
+}
+
+// previousElementTag walks previous siblings to find the nearest non-empty
+// element node. It skips whitespace-only text nodes because HTML parsers often
+// expose formatting whitespace as siblings, returns the lowercase tag name of
+// the first previous element node found, and returns an empty string for nil
+// input or when only non-whitespace text/other nodes are found.
+func previousElementTag(node *nethtml.Node) string {
+	if node == nil {
+		return ""
+	}
+	for sibling := node.PrevSibling; sibling != nil; sibling = sibling.PrevSibling {
+		if sibling.Type == nethtml.TextNode && strings.TrimSpace(sibling.Data) == "" {
+			continue
+		}
+		if sibling.Type == nethtml.ElementNode {
+			return strings.ToLower(sibling.Data)
+		}
+		return ""
+	}
+	return ""
+}
+
+// ensureParagraphBreak mutates the provided *strings.Builder in-place so it
+// ends with one paragraph break. It no-ops for empty builders or existing
+// double-newline endings, appends one newline after a single trailing newline,
+// and appends two newlines otherwise, making it safe to call multiple times.
+func ensureParagraphBreak(out *strings.Builder) {
+	if out.Len() == 0 {
+		return
+	}
+	value := out.String()
+	switch {
+	case strings.HasSuffix(value, "\n\n"):
+		return
+	case strings.HasSuffix(value, "\n"):
+		out.WriteByte('\n')
+	default:
+		out.WriteString("\n\n")
+	}
+}
+
 func ensureLineBreak(out *strings.Builder) {
 	if out.Len() == 0 {
 		return

internal/notify/telegram_format_test.go

@@ -185,6 +185,78 @@ func TestTelegramMarkdownV2PreservesLinks(t *testing.T) {
 	}
 }
 
+func TestTelegramPreservesMarkdownParagraphSpacing(t *testing.T) {
+	body := strings.Join([]string{
+		"**--- Header ---**",
+		"",
+		"Hostname: **server**",
+		"Date/Time: **Today**",
+		"Uptime: **TESTER**",
+		"",
+		"_Beware of a tall blond man with one black shoe._",
+	}, "\n")
+
+	cases := []struct {
+		name     string
+		rawURL   string
+		expected string
+	}{
+		{
+			name:   "markdown v1",
+			rawURL: "tgram://123456:abcdef/7890/?format=markdown&mdv=v1",
+			expected: strings.Join([]string{
+				"*— Header —*",
+				"",
+				"Hostname: *server*",
+				"Date/Time: *Today*",
+				"Uptime: *TESTER*",
+				"",
+				"_Beware of a tall blond man with one black shoe._",
+			}, "\n"),
+		},
+		{
+			name:   "markdown v2",
+			rawURL: "tgram://123456:abcdef/7890/?format=markdown&mdv=v2",
+			expected: strings.Join([]string{
+				"*— Header —*",
+				"",
+				"Hostname: *server*",
+				"Date/Time: *Today*",
+				"Uptime: *TESTER*",
+				"",
+				"_Beware of a tall blond man with one black shoe\\._",
+			}, "\n"),
+		},
+		{
+			name:   "html",
+			rawURL: "tgram://123456:abcdef/7890/?format=html",
+			expected: strings.Join([]string{
+				"<b>— Header —</b>",
+				"",
+				"Hostname: <b>server</b>",
+				"Date/Time: <b>Today</b>",
+				"Uptime: <b>TESTER</b>",
+				"",
+				"<i>Beware of a tall blond man with one black shoe.</i>",
+			}, "\n"),
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			payload := captureTelegramPayload(t, tc.rawURL, body, "", "markdown")
+
+			text, ok := payload["text"].(string)
+			if !ok {
+				t.Fatalf("expected text payload, got %#v", payload["text"])
+			}
+			if text != tc.expected {
+				t.Fatalf("expected Telegram body\n%q\ngot\n%q", tc.expected, text)
+			}
+		})
+	}
+}
+
 func TestTelegramTextFormatUsesHTMLParseMode(t *testing.T) {
 	assertTelegramFormatParity(t, "tgram://123456:abcdef/7890/?format=text", "<b>plain</b>", "Title", "text")
 }