Matrix Announcement

Content guidance for Matrix announcements; matrix-communication does the sending.

The five rules

1. One headline, one purpose. A Matrix message is a tweet, not a blog post.
2. Send formatted_body with the HTML subset. body stays as plaintext fallback. Never send only Markdown — clients are not required to parse it.
3. Lists beat paragraphs. If you're tempted to write "and also …", start a <ul>.
4. Wrap code. Inline <code> for commands, paths, version strings, IDs, env vars — every one of them. Multi-line snippets in <pre><code class="language-…">.
5. Layout > words → render an HTML card to PNG. Comparisons, dashboards, multi-row tables die in formatted_body.

Type tags (pick one — never stack)

Glyphs

One leading glyph at most. Never trailing decoration, multi-emoji ladders, 🚀, or 🎉. Approved: 🤖 bot · 📦 release · 🔧 tooling · 🛡 security · ⚠️ heads-up · 📋 digest · 🔬 RFC · 🚑 hotfix · 🔥 postmortem · ✨ new capability (sparingly).

Pre-send checklist

• Title fits on one line in Element on a 1280-wide screen.
• First sentence states the change. No "we're excited to".
• Every URL wrapped in <a> with destination-as-text.
• Every command, path, version is in <code>.
• Multi-line code in <pre><code class="language-…">.
• At most one prefix glyph; no trailing emoji; no celebration.
• body is a real readable plaintext fallback, not stripped HTML.
• msgtype = m.notice for unattended automation, m.text otherwise.
• No @room unless it is an outage.
• Layout-heavy → card image with text fallback, not <table> in formatted_body.
• Length under 3000 chars or split into a thread.

References

• html-subset.md — allowed/banned tags, Markdown↔HTML, data-mx-* attributes
• structure.md — skeleton, section patterns, element-when-to-use, length budget, m.text vs m.notice
• glyphs.md — full glyph table with banned set
• image-cards.md — chromium → upload → m.image recipe; image-pairing rules
• threading.md — threads, mentions, edits, redactions
• anti-patterns.md — wall-of-text, emoji ladder, mention storm, inline URLs (with fixes)
• text-templates.md — drop-in formatted_body skeletons per type tag
• templates/ — release-card.html (1200×630), weekly-digest.html (1200×1500), comparison.html (1200×900)
• gallery.html — visual preview of every rule, the five worked examples, and the three templates

Sending: pass the composed message to matrix-communication (matrix-send-e2ee.py "$ROOM" "$MARKDOWN" [--notice]). The transport converts markdown to HTML using the rules in html-subset.md; pass --notice for unattended automation so other bots can't auto-reply (mutually exclusive with --emote). For hand-crafted formatted_body or m.image cards, call the homeserver API directly — recipe in image-cards.md.