# Feishu Markdown Format Notes

## Background

Hermes' Feishu gateway (`gateway/platforms/feishu.py`) sends outbound messages
through `_build_outbound_payload`, which checks content for markdown patterns
to decide how to send:

- Content matches `_MARKDOWN_HINT_RE` (bold, lists, code, links, etc.)
  → sent as Feishu `post` type using `md` elements → renders correctly.

- Content matches `_MARKDOWN_TABLE_RE` (a markdown table header + separator)
  → **entire message** forced to `text` type (plain text) → no rendering.

The root cause is that the `_build_markdown_post_payload` helper wraps content
in `{"tag": "md", "text": "..."}` elements, and Feishu's `md` element does not
support table rendering. There is no table-to-native-Feishu-table conversion.

## Rules for Feishu output

- **Never use markdown tables** in any message delivered via Feishu.
  A single table anywhere in the message forces the whole message to plain text.
- Prefer bullet lists, sections with headings, or inline formatting instead.
- Bold (`**bold**`), inline code (`` `code` ``), unordered lists (`- item`),
  ordered lists (`1. item`), and links all work correctly.
- Code fences (``` ``` ```) work but may have edge cases with trailing content.