A self-contained document format for Markdown

The Problem

Markdown is the native output of the AI era — every LLM produces it. But sharing a .md file with images is broken: paths fail, images get lost, you convert to PDF and lose editability. There is no self-contained, portable, human-readable document format between raw Markdown and exported PDF.

MarkBooks fixes this. A .mkb file is a ZIP archive containing Markdown files and their assets. At its simplest, it is a single index.md in a ZIP. At its most capable, it carries multi-chapter documents with illustrations, datasets, cryptographic signatures, and publication timestamps.

Format

Structure

Only index.md is required. A valid MarkBook can be a single Markdown file in a ZIP.

Quick Example

The simplest possible MarkBook:

echo "# Hello, World

This is a MarkBook." > index.md
zip minimal.mkb index.md

That is a valid .mkb file. Open it in Markant or unzip it with any tool.

Principles

1. Trivially implementable. A developer can build a reader in an afternoon.
2. AI-generatable. An LLM can produce a valid MarkBook in one response.
3. Human-readable inside. Unzip and you have plain Markdown.
4. Self-contained. No network required. No external dependencies.
5. Gracefully degrading. Readers render what they support; the rest stays visible as text.
6. Open. CC0 licence. No fees. No proprietary tooling.

Comparison

Advanced Features

Every feature beyond index.md in a ZIP is optional. A minimal reader ignores what it does not support. A full-featured reader can offer:

• Multi-chapter navigation with sidebar table of contents
• Structured metadata via markbook.yaml
• Supporting data — datasets, source code, supplementary materials
• Cross-references — auto-numbered figures, tables, equations
• Content integrity — SHA-256 manifest for tamper detection
• Cryptographic signatures — per-author attestation of content
• Publication timestamps — blockchain-anchored proof of existence
• Version history — embedded Git repository for annotations and revisions

See the full specification for details on each feature.

Resources