Transform .md files into .mx — enriched markdown with AI comprehension layers, voice briefs, and shareable links.
--- mx_version: "1.0" 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 voice brief script is converted to natural audio using open-source TTS. Listen on the web, your phone, or download the MP3.
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 full 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.0 (draft) |
| License | CC BY 4.0 |
| JSON Schema | v1/schema.json |
You publish SKILL.md files. Generate .mx companions so developers can evaluate your skill in seconds instead of reading the full doc.
Your README is 2,000 lines. Give contributors a voice brief they can listen to while setting up their dev environment.
Produce comprehension layers for every doc in your knowledge base. Non-technical stakeholders get the ELI5. Engineers get the full spec.
Point gist.mx at your repo. Get a project-level summary that synthesizes all your markdown files into one briefing with cross-file intelligence.
The .mx spec is CC BY 4.0. Implement parsers, generators, and viewers. The service is coming soon. The format is ready now.