MDZip on mobile: libraries for Android and iOS

[kylemwhite]

MDZip (.mdz) now has native libraries for both phone platforms. org.mdzip:mdzip-core is for Android (Kotlin or Java), and mdzip-core-swift is for iOS (Swift). Both read, write and validate .mdz files, and both pass the same shared conformance tests from the specification as the .NET, JavaScript, Python, Rust and Lua libraries. A document saved on a phone opens the same way in MDZip Studio, VS Code or Obsidian, and the other way round.

Android

For Android 5.0 and later. It's a plain Kotlin library, so it also works in desktop and server apps on Java 8 and later, from Kotlin or Java. No dependencies beyond the Kotlin standard library.

dependencies {
    implementation("org.mdzip:mdzip-core:0.1.0")
}

// A file the user picked, opened through the ContentResolver.
val archive = contentResolver.openInputStream(uri)!!.use { MdzArchive.open(it) }
val markdown = archive.readText(archive.entryPoint())     // index.md
val photo = archive.readBytes("images/beach.png")

iOS

For iPhone and iPad on iOS 15 and later. The same package works in Mac apps (macOS 12 and later) and on Linux, so one codebase can handle .mdz on every Apple device. Add it in Xcode under File → Add Package Dependencies… with https://github.com/mdzip-project/mdzip-core-swift, or in Package.swift:

.package(url: "https://github.com/mdzip-project/mdzip-core-swift.git", from: "0.1.0")

import MDZip

let archive = try MDZipArchive(contentsOf: url)           // a file from the document picker
let markdown = try archive.text(at: try archive.entryPoint())
let photo = try archive.data(at: "images/beach.png")

What they do

• Open what people share. An .mdz is one file with the Markdown and its images together, so it survives email, messaging apps, AirDrop and cloud drives. The libraries read it straight from memory or a stream, without unzipping anything to storage.
• Write conforming files. Every archive gets the manifest.json the specification requires, with the main document recorded, so other tools open the right file.
• Change files safely. Updating an archive keeps everything you didn't touch, including images, files your app doesn't know about and manifest fields other apps wrote. If the change would break the archive, nothing is written.
• Open untrusted files safely. Unsafe paths, ZIP bombs and symbolic links are rejected or ignored, with a stable error code your app can check.

The libraries don't render Markdown; your app shows it with the Markdown view it already uses.

Tested on every change: on Android 5.0, 7.0, 10 and 15 emulators and Java 11 and 17 for the Kotlin library, and in the iOS Simulator, on macOS and on Linux for the Swift one.

What's next

If you're adding .mdz to an app, Core libraries compares all seven, and Works with MDZip shows everything that reads and writes it today. Building something on a phone? Tell us in Discussions; we'd like to list it.

Android library on Maven Central · Android source and API reference · iOS library source and API reference · Release notes: Android, iOS

_{Kotlin is a trademark of JetBrains s.r.o. Swift and the Swift logo are trademarks of Apple Inc. Neither is affiliated with or endorses MDZip.}