Transform .md files into .mx — enriched markdown with AI comprehension layers, voice briefs, and shareable links.
--- mx_version: "1.1" source: "README.md" source_hash: "sha256:e3b0c4..." oneliner: "An open format that adds AI comprehension layers to markdown." gist: | The .mx format extends markdown with AI-generated understanding — a one-liner, a gist, a voice brief, and an ELI5 — bundled in YAML frontmatter. Any markdown tool can still read it. MX-aware tools unlock the full experience. voice_brief: script: | So here's the idea behind .mx. You've got a markdown file, maybe a README or a spec — and nobody has time to read the whole thing. MX fixes that... duration_seconds: 120 eli5: | Imagine a book that whispers what it's about before you even open it. That's what .mx does for documents! --- # .mx Format Specification The original markdown content follows unchanged...
Every .mx file contains the original markdown plus five comprehension layers — each designed for a different way of consuming information.
A single sentence. The tweet-length version. Max 280 characters. What you'd skim in a list of 200 files.
Three to five sentences. The elevator pitch. What you'd say if someone asked "what's this about?"
A conversational script purpose-written for audio. Not a summary read aloud — written for the ear, not the eye.
Explain Like I'm 5. Simple words, fun analogies, wonder-preserving. Makes complex ideas feel magical.
The original markdown, beautifully rendered with navigable sidebar. Because sometimes you need the whole thing — but now you have context before you dive in.
.mx is a superset of markdown. It's backward compatible — open it in any editor and it's just markdown with YAML frontmatter. But an MX-aware viewer unlocks the full experience.
Upload a .md file, paste a URL, point at a GitHub repo, or pipe it through the CLI.
Open-source language models generate five comprehension layers — each tuned for a different consumption context.
The model writes a 2-minute voice brief script you can read, edit, and use in your own narration or TTS workflow.
Download the enriched file, view it on a hosted link, share it with your team, or commit it alongside your .md in version control.
The format is open, documented, and backward compatible. Every .mx file is valid markdown. The comprehension layers are purely additive metadata in YAML frontmatter. Read the v1.1 spec on GitHub.
| Property | Value |
|---|---|
| MIME type | text/vnd.gist.mx |
| File extension | .mx |
| Encoding | UTF-8 |
| Structure | YAML frontmatter + CommonMark/GFM body |
| Backward compatible | Yes — valid markdown in any editor |
| Spec version | 1.1 |
| v1.1 update | Signature block added for authenticity verification |
| License | CC BY 4.0 |
| JSON Schema | v1.1/schema.json |
Teams that write a lot of markdown and want faster comprehension without rewriting their docs workflow.
You publish SKILL.md files. Generate .mx companions so developers can evaluate fit fast before deep-diving into implementation details.
Your README is long and evolving. Offer one-liner, gist, voice brief, and ELI5 layers so contributors ramp up quickly.
Ship comprehension layers for high-value docs so non-technical readers get clarity and technical readers keep full-fidelity source.
Use gist.mx on important markdown docs one file at a time so human teammates and in-team agents can consume the same shared brief before deeper work.
The .mx spec is CC BY 4.0. Implement parsers, generators, and viewers. The service is in public beta, and the format is ready now.