render-markdown

name	render-markdown
description	Render a normalized ChatGPT conversation to Markdown with user and assistant turns marked, YAML front matter, a stats block and a sources section. Use after capturing and normalizing a conversation.

Render to Markdown

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/render_conversation.py" <normalized.json> \
  --user-label "User" --assistant-label "ChatGPT" -o <out.md>

Options that matter

Flag	Use it for
--user-label	User for agent context, a real name for something a person reads
--sources section|footnotes|none	section lists sources at the end (default); footnotes also marks the turns that cited them
--timestamps	Per-turn time — useful for a long thread, noise for a short one
--no-front-matter	Pasting into an existing document
--no-summary	Drop the stats table
--heading-level N	Turn heading depth, default 2
--format text	Strip front matter, keep the body

Output shape

---
title: ...            date_held: 2026-08-24
total_turns: 34       user_messages: 17      assistant_messages: 17
model: gpt-5-6        url: ...               captured_at: ...
---

# <title>
<stats table>

## User
...
## ChatGPT (gpt-5-6)
...
## Sources
1. [Title](url) — first cited in turn 4

Headings inside messages

ChatGPT writes its own ## headings inside answers. Emitted as-is under a ## turn heading they become siblings of it, and the document outline stops showing where turns begin — any heading-based splitter then mis-slices the transcript. The renderer demotes in-message headings below the turn level automatically, skipping fenced code. If you change --heading-level, demotion follows it; you do not need to compensate.

Checking the result

Turn headings should equal total_turns:

grep -c '^## ' <out.md>

If that number exceeds the turn count, demotion did not run — the transcript is still readable but is no longer safe to split on headings.