Dotbook · Ink Reader Docs

Why Dotbook exists

EPUB is excellent for distribution, but its HTML, CSS, navigation, and packaging rules give reading apps a large surface to interpret. Dotbook narrows that surface: it keeps the content structured, defines obvious defaults, and makes packaged and streamed books look alike to a reader.

Human-readable manifests and chapter files.
Predictable locations for covers, assets, frontmatter, chapters, and postmatter.
Rich, sanitized nodes without arbitrary executable content.
Stable resource identifiers for caching, highlights, translation, and narration.

Package layout

A packaged Dotbook is a ZIP-compatible archive using the .book extension. A minimal book can rely on convention instead of listing every file.

Directory tree

my-novel.book
├── book.yaml
├── cover.webp
├── assets/
│   └── map.webp
├── frontmatter/
│   └── 001-title.md
├── chapters/
│   ├── 001-awakening.md
│   ├── 002-the-road.md
│   └── 003-storm.md
└── postmatter/
    └── 001-afterword.md

When an explicit reading order is absent, readers scan the content folders and sort filenames naturally. Prefixes such as 001- are the clearest convention; suffixes such as -001 may also be recognized.

Book manifest

book.yaml connects metadata and resources. The JSON representation uses the same field names so a web service can expose the manifest without inventing another model.

book.yaml

format: dotbook
version: "1"
id: urn:dotbook:the-glass-sea
title: The Glass Sea
language: en
authors:
  - name: Mina Vale
description: A cartographer follows a coastline that moves each night.
cover: cover.webp
content:
  chapters: chapters/
  frontmatter: frontmatter/
  postmatter: postmatter/
chapterFormat: text/markdown

Defaults

The cover is the first matching root file named cover.jpg, cover.png, cover.webp, or cover.avif.
Chapter files live under chapters/.
Frontmatter and postmatter are optional.
Relative resource paths are resolved inside the book boundary and may not escape it.

Prefer stable IDs.

A stable book ID and stable chapter IDs let reading progress, annotations, edits, and cached resources survive file renames and provider URL changes.

Chapter content

Plain chapters may use Markdown. Books that need normalized rich content can use Mark JSON with the media type application/vnd.mark+json.

chapter.json

{
  "version": "1",
  "id": "chapter-001",
  "title": "Awakening",
  "blocks": [
    {
      "type": "paragraph",
      "children": [
        { "type": "text", "text": "Rain pressed silver lines across the glass." }
      ]
    },
    {
      "type": "image",
      "src": "assets/map.webp",
      "alt": "A map of the northern coast"
    }
  ]
}

Renderers should ignore unknown optional nodes, reject unsafe resource paths, and never execute scripts embedded in content. Rich nodes should describe meaning, not dictate a particular screen layout.

Streamable books

A streamable Dotbook exposes the same logical resources independently. Clients can fetch the small manifest first, then retrieve only the chapter and assets needed for the current reading session.

GET/manifestBook metadata, capabilities, and resource links.

GET/chaptersOrdered chapter index with stable IDs.

GET/chapters/{id}One Markdown or Mark JSON chapter.

GET/assets/{path}Cover art and chapter resources.

Concern	Packaged .book	Streamed book
Manifest	Archive root	JSON response
Chapters	Files in the archive	Fetched by stable ID
Assets	Relative archive paths	URL or resource endpoint
Offline use	Immediate	Resource cache or export

HTTP servers should provide validators such as ETag or Last-Modified. Clients can then revalidate cheaply and keep immutable chapter content for long periods.

Portable libraries

The related .library container represents a collection of books and reading state. It may embed Dotbooks or retain references to remote books, plus progress, history, collections, annotations, and preferences.

This keeps a reader profile backupable and shareable without making an Ink Reader account the only copy. Library data is a separate layer from the Dotbook itself, so sharing a book does not accidentally share private reading history.