RFC Draft v1.0

MarkDown Open Container eXchange

A single-file container format for bundling Markdown documents with embedded media (images, audio, video). Perfect for exchange, archival, and transport.

Download CLIView on GitHub
Self-contained
Multi-language SDKs
MIT Licensed
Origin Story

Born from the AI Era

As Large Language Models revolutionized content creation, a new challenge emerged: managing the flood of Markdown-formatted output generated by AI systems.

AI Solutions Architect Martijn Wiggers recognized the need for a file format that could cluster related Markdown documents together — complete with their referenced images, diagrams, and other media — into a single, portable container.

The result is MDOCX: designed with an uncompressed metadata block at the start of each file, making it trivially easy for search engines, indexers, and AI systems to peek at document contents without decompressing the entire payload.

The Problem
LLM outputs need organization
1
Scattered Content
AI generates .md files with image references pointing to separate files
2
Broken Links
Sharing or archiving breaks image paths and media references
3
Hard to Index
No standard way to search or catalog related documents
MDOCX solves this — one file, all content, instantly indexable.

ChatGPT Can Create MDOCX Files

Start your ChatGPT prompt with: Use `pip install logicossoftware-mdocx` to create mdocx with markdown files containing...

Features

Why MDOCX?

Designed for simplicity, efficiency, and cross-platform compatibility

Containerization
Bundle multiple Markdown files and associated media in one portable file.
Self-contained References
Markdown references media by stable IDs and container paths using mdocx:// URIs.
Efficient Parsing
Deterministic header and length-delimited sections for fast processing.
Extensibility
Forward-compatible via versioning, flags, and gob field evolution.
Multiple Compression
Support for ZIP, Zstandard, LZ4, and Brotli compression algorithms.
Security Built-in
SHA256 integrity hashes, size limits, and decompression bomb protection.
Specification

File Format Structure

A well-defined binary format with fixed header, metadata, and content sections

File Layout

32 bytesFixed Header
OptionalMetadata Block (UTF-8 JSON)
Section 1Markdown Bundle (gob-encoded)
Section 2Media Bundle (gob-encoded)

Header Fields

OffsetSizeName
08Magic
82Version
102HeaderFlags
124FixedHeaderSize
164MetadataLength

Magic: MDOCX\r\n + 0x1A

Read Full RFC Specification
SDKs & Tools

Available Implementations

Official SDKs and tools for working with MDOCX files across multiple platforms

GoReference
go-mdocx
Reference implementation of MDOCX file format with full RFC compliance. Includes C DLL interface.
go get github.com/logicossoftware/go-mdocx
View Repository
TypeScript
ts-mdocx
Full-featured TypeScript implementation with builder API, validation, and CLI tool.
npm install ts-mdocx
View Repository
Python
py-mdocx
Python implementation with optional compression support for Zstandard, LZ4, and Brotli.
pip install logicossoftware-mdocx
View Repository
CLICLI Tool
mdocx-cli
Command-line toolkit for packing, unpacking, validating, and browsing MDOCX containers.
go install github.com/logicossoftware/mdocx-cli@latest
View Repository
VS CodeExtension
mdocx-vscode
Preview, edit, and manage MDOCX files directly in Visual Studio Code with live preview.
code --install-extension logicos.mdocx-vscode
View Repository
WebOnline
MDOCX Viewer
View, edit, and create MDOCX files directly in your browser. No installation required.
Open Viewer
Compression

Flexible Compression Options

Choose the right compression algorithm for your use case

AlgorithmCodeBest For
None0x0Debugging, already-compressed content
ZIP/DEFLATE0x1Maximum interoperability
ZstandardRecommended0x2Best speed/ratio trade-off
LZ40x3Maximum speed
Brotli0x4Maximum compression ratio
Quick Start

Get Started in Seconds

Simple APIs for reading and writing MDOCX files

import { readFile } from 'node:fs/promises';
import { readMdocx, createBuilder, writeMdocxAsync } from 'ts-mdocx';
 
// Read an MDOCX file
const bytes = await readFile('document.mdocx');
const doc = await readMdocx(bytes);
 
console.log('Files:', doc.markdown.files.length);
console.log('Media:', doc.media.items.length);
 
// Create a new MDOCX file
const newDoc = createBuilder()
  .title('My Document')
  .root('index.md')
  .addMarkdown('index.md', '# Hello World')
  .build();
 
const output = await writeMdocxAsync(
  newDoc.markdown,
  newDoc.media,
  { markdownCompression: 'zstd' }
);

Ready to Get Started?

Download the CLI tool, install an SDK, or check out the VS Code extension to start working with MDOCX files today.

Try Online ViewerDownload CLIVS Code Extension