Chat Transcript Styling in GitHub Flavored Markdown (GFM)

You said you render the user message and assistant response in the same file, so they need to be visually distinct. This gist is a grab bag of GFM-native patterns that render well on GitHub (including gists).

Each option shows a rendered example first, then a copy/paste-able source snippet.

---

Option 1: Headings + horizontal rules (simple, clean)

User

How do I list all files in a directory?

Assistant

Use ls (macOS/Linux) or dir (Windows).

---

#### User

How do I list all files in a directory?

#### Assistant

Use `ls` (macOS/Linux) or `dir` (Windows).

---

---

Option 2: Alerts (callouts/admonitions) for strong role styling

Note

User

My tests are flaky. What should I check first?

Tip

Assistant

Start by isolating sources of nondeterminism (time, randomness, concurrency) and run with retries disabled.

---

> [!NOTE]
> **User**
>
> My tests are flaky. What should I check first?

> [!TIP]
> **Assistant**
>
> Start by isolating sources of nondeterminism (time, randomness, concurrency) and run with retries disabled.

Notes:

• Alerts are a GitHub extension based on blockquotes. Types: NOTE, TIP, IMPORTANT, WARNING, CAUTION.
• GitHub Docs says alerts can't be nested and recommends avoiding back-to-back alerts (in practice, alternating like this often works).

---

Option 3: Two-column table (compact, scannable)

Role	Message
User	Can you refactor this function to be more readable?
Assistant	Yes. First, extract the parsing logic into a helper and add a small unit test.

---

| Role | Message |
| --- | --- |
| **User** | Can you refactor this function to be more readable? |
| **Assistant** | Yes. First, extract the parsing logic into a helper and add a small unit test. |

Tip: If you need line breaks inside a table cell, GitHub generally requires HTML like <br>.

---

Option 4: Diff fenced code block (high contrast, role = +/-)

- User: Please remove the feature gate and ship it.
+ Assistant: I can do that. Before I remove it, do we still need an emergency rollback path?

---

```diff
- User: Please remove the feature gate and ship it.
+ Assistant: I can do that. Before I remove it, do we still need an emergency rollback path?
```

Tradeoff: Great contrast, but you lose rich Markdown inside the messages (everything is monospace).

---

Option 5: Task list (role as checkbox state)

• User: Add logging for the retry loop.
• Assistant: Done. I added a rate-limited log line and a test that asserts the message format.

---

- [ ] **User:** Add logging for the retry loop.
- [x] **Assistant:** Done. I added a rate-limited log line and a test that asserts the message format.

---

Option 6: Collapsible messages with <details> (great for long outputs)

User

Can you explain how this caching layer works?

Assistant

It memoizes results by key, but also tracks TTL and invalidates on writes. The subtle part is that the TTL clock starts at insert, not read.

---

<details>
<summary><strong>User</strong></summary>

Can you explain how this caching layer works?

</details>

<details>
<summary><strong>Assistant</strong></summary>

It memoizes results by key, but also tracks TTL and invalidates on writes. The subtle part is that the TTL clock starts at *insert*, not *read*.

</details>

Tradeoff: This uses inline HTML (still supported in GitHub-flavored Markdown rendering).

---

Option 7: Separate fences per role (preserve whitespace + different highlighting)

[User]
Please keep my exact spacing.
  - This line is indented.
  - So is this one.

[Assistant]
Got it. I'll preserve whitespace and render lists exactly as written.

---

```text
[User]
Please keep my exact spacing.
  - This line is indented.
  - So is this one.
```

```markdown
[Assistant]
Got it. I'll preserve whitespace and render lists exactly as written.
```

---

Option 8: Hidden metadata with HTML comments (parseable, not visible)

User

Please summarize this log file.

Assistant

Sure. The dominant error is a connection timeout during startup.

---

#### User

<!-- role: user -->
<!-- ts: 2026-01-25T17:55:00Z -->

Please summarize this log file.

#### Assistant

<!-- role: assistant -->
<!-- model: gpt-5 -->

Sure. The dominant error is a connection timeout during startup.

---

Option 9: Footnotes for citations/links (useful in assistant replies)

User

Why are you recommending this approach?

Assistant

Because it keeps the hot path allocation-free and makes the slow path explicit.¹

---

#### User

Why are you recommending this approach?

#### Assistant

Because it keeps the hot path allocation-free and makes the slow path explicit.[^alloc]

[^alloc]: On GitHub, footnotes use `[^1]` references and `[^1]: ...` definitions.

---

Quick picks

• If you want very simple: Option 1.
• If you want strong visual distinction without code blocks: Option 2.
• If you want dense transcripts: Option 3.
• If you want max contrast for quick scanning: Option 4.
• If assistant messages can get huge: Option 6.

Footnotes

1. On GitHub, footnotes use [^1] references and [^1]: ... definitions. ↩