Why open-context Exports Conversations as Markdown
open-context converts every ChatGPT conversation into a plain Markdown (.md) file instead of
keeping the original JSON, because Markdown is readable by both people and language models without any
extra parsing step. Each file carries the conversation title, timestamps, and a clearly labeled sequence
of user and assistant turns — structure a model can use, in a format a person can open in any text editor.
That single choice is what lets the same output double as Claude Project
knowledge, a searchable local archive, and a plain-text file you can diff in version control.
Key takeaways
- open-context's
MarkdownFormatterturns each conversation into one self-contained.mdfile: an H1 title, bold metadata lines, then an H2 heading per turn (User, Assistant, or System). - Markdown's lighter token footprint than JSON or HTML means more of a model's context window goes to the actual conversation instead of markup — Microsoft's MarkItDown project notes that "Markdown conventions are also highly token-efficient."
- Claude's documented Project upload list doesn't name the
.mdextension specifically — it lists PDF, DOCX, CSV, TXT, HTML, ODT, RTF, EPUB, and JSON — but Markdown content works regardless, since Claude reads the text itself, not the file extension. - Every filename is sanitized and zero-padded (
001-first-conversation.md) bygenerateFilename(), and anindex.mdfile lists every conversation in order so nothing requires a database to browse. - Titles are escaped before they reach a heading —
#,*, and_are backslash-escaped — so a conversation titled "#1 Notes" can't break the Markdown it's rendered into.
The export problem Markdown solves
ChatGPT's own export isn't built for reading. conversations.json stores your entire history
as a flat mapping object keyed by message ID, with each node pointing at a parent and a list
of children — you have to walk that tree just to get one conversation back in order. That representation
makes sense for a client that already has a tree-walking renderer. It's unreadable if you open it
directly, and pasting the raw JSON into a chat with Claude burns tokens on brackets, quotes, and key
names instead of your actual words.
open-context's conversion pipeline — covered in more depth in From ChatGPT Export to Claude Format — exists to close that gap: parse the export, normalize every message into a common schema, then hand the result to a formatter. Markdown is the formatter it ships with, not because producing JSON would have been harder, but because the output needed to be something a person reads directly and a model reads cheaply.
What the Markdown output actually looks like
src/formatters/markdown.ts builds each conversation file the same way every time. A
typical output looks like this:
# How to debug a flaky test
**Created:** 2026-08-01
**Last Updated:** 2026-08-01
**Messages:** 2
---
## User
Why does this test only fail in CI?
## Assistant
A few common causes: shared state between test runs, timezone...
*Model: gpt-4*
---
*Exported from ChatGPT via opencontext*
Three details in that file are doing real work. The role headers (## User,
## Assistant) give the model an unambiguous turn boundary without inventing a custom
delimiter. The metadata block at the top is bolded Markdown, not a separate JSON sidecar, so a reader
gets context without switching files. And generateFilename() sanitizes the title and
zero-pads an index — 007-debug-flaky-test.md — so a folder of hundreds of conversations
still sorts and scans in a normal file browser.
A second function, formatIndex(), writes one additional file,
index.md, that lists every converted conversation with its filename, creation date, and
message count — a table of contents you can open without any tool beyond a text editor.
Why Markdown over JSON or HTML for this specific job
JSON and HTML both carry structure, but neither carries it cheaply for prose. Microsoft's MarkItDown project — built specifically to prepare documents for LLM consumption — states plainly that "Markdown conventions are also highly token-efficient," and notes that mainstream LLMs tend to produce Markdown unprompted in their own responses, which it takes as a sign of how much Markdown the models were trained on. Neither JSON's escaped quotes and bracket nesting nor HTML's opening and closing tags add meaning for a conversation transcript — they're overhead a model has to read past before it reaches the words that matter.
That tradeoff is specific to this use case. JSON is still the right call for open-context's own REST API and its MCP tool responses, where a client needs exact, typed fields. For a document meant to be read — by a person skimming it or a model summarizing it — flat headings and bold labels do the same structural job as JSON's keys and HTML's tags, at a fraction of the character count.
Markdown and Claude Projects: the extension nuance
One thing worth being precise about: Claude's own documentation for file uploads to a Project lists
PDF, DOCX, CSV, TXT, HTML, ODT, RTF, EPUB, and JSON as supported document types — it does not name the
.md extension by itself. In practice this rarely matters. Claude ingests the text content
of a file, not its extension, so a Markdown file saved with a .txt extension, or Markdown
text pasted directly into a Project's knowledge or into chat, behaves identically to a native upload —
the headings and bold text still parse as structure, because that's just how the characters read.
If you want to be extra safe about an upload being recognized, rename the file from .md to
.txt before adding it; the content inside doesn't need to change at all.
What this means for your own export
Run npm run dev convert path/to/chatgpt-export.zip or use the web UI, and the
conversations/ folder you get back is plain Markdown end to end — no proprietary format,
no lock-in, and nothing that requires open-context itself to read later. Upload the whole folder to a
Claude Project as knowledge, paste a single conversation into a chat when you need it as context, or
just keep it as a local, searchable archive of a service that was never going to let you export it this
cleanly on its own.
Convert your own ChatGPT export to Markdown in minutes.
Get started with open-context →FAQ
Does open-context export ChatGPT conversations as Markdown files?
Yes. open-context's MarkdownFormatter converts each conversation into a standalone .md file with a title, metadata, and one heading per message, plus an index.md file that lists every conversation in order.
Can I upload open-context's Markdown files directly to a Claude Project?
In practice, yes, though Claude's documented Project file list names PDF, DOCX, CSV, TXT, HTML, ODT, RTF, EPUB, and JSON rather than the .md extension by name. Claude reads the text content, not the file extension, so pasting the Markdown directly or saving it with a .txt extension behaves the same way.
Does converting to Markdown lose any information from the original ChatGPT export?
No message content is lost — role, text, timestamps, images, attachments, and the model name all carry through the normalizer before formatting. What it doesn't special-case is ChatGPT's branching: the parser walks the message tree breadth-first from the root, so regenerated or alternate replies can appear in the output alongside the branch ChatGPT's UI shows as current.
Why does open-context use Markdown instead of exporting JSON directly?
JSON is what ChatGPT exports, but it's built for a renderer, not a reader — nested keys and escaped strings cost tokens without adding meaning for a conversation. Markdown keeps the same content behind plain headings a person can skim and a model can parse without stripping markup first.
What happens to images and attachments in the Markdown output?
Each image or attachment is written as a bracketed reference line, like [Image: file-abc123], directly under the message it belongs to, and open-context separately copies the actual image files from the export into an images/ folder next to the conversation markdown.