mdocx

go-mdocx

Go implementation of the MDOCX (MarkDown Open Container eXchange) file format — a single-file container for bundling Markdown documents with referenced media (images, audio, video, etc.).

Features

• 📦 Single-file container — Bundle multiple Markdown files and media assets into one .mdocx file
• 🗜️ Multiple compression options — Zstandard (default), ZIP, LZ4, Brotli, or no compression
• 🔒 SHA-256 integrity — Optional hash verification for media items
• 📝 Rich metadata — JSON metadata block for document properties
• 🔗 Media reference resolution — Resolve mdocx://media/<ID> URIs and relative paths
• ⚡ Efficient parsing — Deterministic header and length-delimited sections
• 🛡️ Security built-in — Configurable limits protect against resource exhaustion

Installation

go get github.com/logicossoftware/go-mdocx

Requires Go 1.21 or later.

Quick Start

Creating an MDOCX file

package main

import (
    "os"
    "github.com/logicossoftware/go-mdocx"
)

func main() {
    doc := &mdocx.Document{
        Metadata: map[string]any{
            "title":   "My Document",
            "creator": "Jane Doe",
        },
        Markdown: mdocx.MarkdownBundle{
            BundleVersion: mdocx.VersionV1,
            Files: []mdocx.MarkdownFile{
                {
                    Path:    "readme.md",
                    Content: []byte("# Hello World\n\nThis is my document."),
                },
            },
        },
        Media: mdocx.MediaBundle{BundleVersion: mdocx.VersionV1},
    }

    f, _ := os.Create("output.mdocx")
    defer f.Close()
    
    err := mdocx.Encode(f, doc)
    if err != nil {
        panic(err)
    }
}

Reading an MDOCX file

package main

import (
    "fmt"
    "os"
    "github.com/logicossoftware/go-mdocx"
)

func main() {
    f, _ := os.Open("input.mdocx")
    defer f.Close()

    doc, err := mdocx.Decode(f)
    if err != nil {
        panic(err)
    }

    fmt.Printf("Title: %v\n", doc.Metadata["title"])
    fmt.Printf("Files: %d\n", len(doc.Markdown.Files))
    fmt.Printf("Media: %d\n", len(doc.Media.Items))
}

With media and compression options

import "crypto/sha256"

// Create document with media
imageData := []byte{...} // your image bytes
hash := sha256.Sum256(imageData)

doc := &mdocx.Document{
    Metadata: map[string]any{"title": "Document with Image"},
    Markdown: mdocx.MarkdownBundle{
        BundleVersion: mdocx.VersionV1,
        Files: []mdocx.MarkdownFile{
            {
                Path:      "readme.md",
                Content:   []byte("# My Doc\n\n![Logo](mdocx://media/logo)"),
                MediaRefs: []string{"logo"},
            },
        },
    },
    Media: mdocx.MediaBundle{
        BundleVersion: mdocx.VersionV1,
        Items: []mdocx.MediaItem{
            {
                ID:       "logo",
                Path:     "assets/logo.png",
                MIMEType: "image/png",
                Data:     imageData,
                SHA256:   hash,
            },
        },
    },
}

// Encode with custom compression
err := mdocx.Encode(f, doc,
    mdocx.WithMarkdownCompression(mdocx.CompZSTD),
    mdocx.WithMediaCompression(mdocx.CompLZ4),
)

Compression Options

Encoding Options

mdocx.Encode(w, doc,
    mdocx.WithMarkdownCompression(mdocx.CompZSTD),  // Compression for markdown section
    mdocx.WithMediaCompression(mdocx.CompZSTD),     // Compression for media section
    mdocx.WithAutoPopulateSHA256(true),             // Auto-compute SHA256 for media (default: true)
    mdocx.WithVerifyHashesOnWrite(true),            // Verify hashes before writing (default: true)
    mdocx.WithWriteLimits(mdocx.DefaultLimits()),   // Custom size limits
)

Decoding Options

doc, err := mdocx.Decode(r,
    mdocx.WithVerifyHashes(true),                   // Verify SHA256 on media items (default: true)
    mdocx.WithReadLimits(mdocx.Limits{              // Custom size limits
        MaxMediaUncompressed: 4 << 30,              // Allow up to 4 GiB media
    }),
)

Default Limits

The package enforces configurable limits to protect against malicious input:

Examples

The examples/ directory contains runnable examples:

Run an example:

cd examples/create-basic
go run .

File Format

MDOCX files consist of:

1. Fixed header (32 bytes) — Magic bytes, version, flags
2. Metadata block (optional) — UTF-8 JSON
3. Markdown section — One or more Markdown files (gob-encoded, optionally compressed)
4. Media section — Zero or more media items (gob-encoded, optionally compressed)

For the complete specification, see rfc.md.

Magic Bytes

4D 44 4F 43 58 0D 0A 1A  ("MDOCX\r\n" + 0x1A)

Media References

Reference media from Markdown using:

• By ID: ![Logo](mdocx://media/logo_id)
• By path: ![Logo](assets/logo.png) (if MediaItem.Path is set)

Media Resolution

The package provides a MediaResolver for resolving media references:

// Create resolver from document
resolver := mdocx.NewMediaResolver(doc)

// Get by ID
item := resolver.GetByID("logo")

// Get by path
item := resolver.GetByPath("assets/logo.png")

// Resolve any reference (mdocx:// URI or path)
item := resolver.Resolve("mdocx://media/logo")
item := resolver.Resolve("assets/logo.png")

// Check existence
if resolver.HasID("logo") {
    // ...
}

// Get all media referenced by a markdown file
refs := resolver.GetReferencedMedia(&doc.Markdown.Files[0])

// List all IDs and paths
ids := resolver.IDs()
paths := resolver.Paths()

List Media Contents

Read only media items without fully decoding the markdown bundle:

f, _ := os.Open("document.mdocx")
defer f.Close()

items, err := mdocx.ListMediaContents(f)
for _, item := range items {
    fmt.Printf("%s: %s (%d bytes)\n", item.ID, item.MIMEType, len(item.Data))
}

Parse Media Reference

Parse a reference string to determine its type:

ref := mdocx.ParseMediaReference("mdocx://media/logo")
// ref.Type == "id", ref.ID == "logo"

ref := mdocx.ParseMediaReference("assets/image.png")
// ref.Type == "path", ref.Path == "assets/image.png"

API Reference

See the Go package documentation for complete API details.

Core Types

• Document — Top-level container
• MarkdownBundle — Collection of Markdown files
• MarkdownFile — Single Markdown document
• MediaBundle — Collection of media items
• MediaItem — Single media asset

Core Functions

• Encode — Write a document to an MDOCX file
• Decode — Read a document from an MDOCX file
• ListMediaContents — List media items without full decode

Media Resolution

• MediaResolver — Resolve media by ID, path, or URI
• NewMediaResolver — Create a new resolver
• ParseMediaReference — Parse a reference string

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

License

MIT License — Copyright (c) 2026, MHJ Wiggers / Logicos Software