Skip to content
Boeks

Appearance

Theme

Library layout

Where everything is in a library folder: the books, their editions, and the small files beside them.

1. Library layout

Library/
  .boeks/
    boeks.json                    # the library's settings; marks the root (§1.2)
    cache/                        # derived, and disposable (§4)
      library.json                # the index
      covers/<edition-id>.jpg     # each edition's cover
    mac-studio-4f2.jsonl          # library-level logs, one per device (§5)
    iphone-7k3.jsonl
  Frank Herbert/
    Dune/                         # a book (§2)
      Book.md                     # status, rating, collections, and review (§6.2)
      Ebook (en)/                 # an edition (§1.3), the primary one
        Dune - Frank Herbert.epub
        Edition.md                # that edition's annotations (§6.3)
      Ebook (nl)/                 # another edition, a translation
        Duin - Frank Herbert.epub
      Audiobook/                  # an audiobook, also an edition (§9)
        Dune - Frank Herbert.m4b
      .boeks/
        iphone-7k3.jsonl          # book-level logs, one per device (§5)
        kobo-libra-x7m.jsonl
        covers/<sha256>.jpg       # covers set by edits (§3.6)
        alignments/<audiobook>-<ebook>.json  # an audiobook aligned with its ebook (§9.2)

1.1 The .boeks/ folders

  • What's in a folder named .boeks/ belongs to the format. Everything else in a library is the reader's: the editions' folders and files, Book.md, and each edition's Edition.md.
  • The root is the folder whose .boeks/ holds boeks.json.
  • A book folder is any folder below the root with a .boeks/ of its own, at most 8 folders down, wherever it is: a moved book is still a book. Nothing inside a book folder is looked through for other books. Hidden folders, readers' sidecars (*.sdr), and symbolic links are passed over, so reading stays inside the library. An EPUB outside any book folder is a file to import.
  • The folders are hidden, so file browsers and e-readers show a book folder with only the reader's files in it. A library has to be synced with its hidden folders: without a book's .boeks/, its progress and highlights are gone. Some sync services leave hidden folders out unless told otherwise.
  • A Book.md or an edition's folder without a .boeks/ beside it is a book whose .boeks/ hasn't arrived, since only a book with a .boeks/ gets a Book.md, and only Boeks names folders as editions' (Ebook, Audiobook, alone or with qualifiers, §1.3). An unread book without a rating or collections has no Book.md, so its edition folders are what show it. Don't import its editions as a new book, and don't create a library over such a folder: either would compete with the book or library still syncing.

1.2 boeks.json

{
  "version": 1,
  "settings": { … }
}
  • version is the library's format version: its layout, boeks.json, the logs and their events, and the files of §6. The index (§4) and each shared work file (§1.4) have a version of their own, for how they're made: a device makes one of an older version again, and leaves one of a newer version alone.
    • It goes up only for a change older tools can't read safely, such as an event whose meaning changes or a file that moves. An addition, such as a new field, event type, value, or setting, leaves it as it is, since readers pass over what they don't know (§5.2).
    • A tool that meets a higher version than it knows opens the library read-only, and writes nothing to it, e-reader plugins included.
    • Moving a library to a new version rewrites only boeks.json and the derived files (§4), never a device's log.
  • settings are the library's own, the same on every device. settings.transforms lists the transforms to run on import (§3.4), none unless the library sets some, and settings.fetch which metadata providers to ask online, in order, and how their genres are taken (§11). Keep the settings you don't know as they are.
  • Rewriting it: whichever device changes a setting rewrites the file, keeping the fields it doesn't know.

1.3 Folder and file names

Every library is filed the same way, so each device puts a book in the same place.

  • Book folders are {author}/{title}, with the author folders at the root.
  • The author is the first dc:creator with role aut, in the OPF's order, by its display name (not file-as). Without one, the first edt, for anthologies; without that, the first creator with no role; and without any, or with a name that's empty once made safe (below), Unknown Author.
  • The title is the edition's title, or Untitled without one, or with one that's empty once made safe.
  • Two books with the same author and title: the one named second gets its year in parentheses after the title (Dune (1965)), or when that's taken too, the first number from 2 that's free (Dune (2)). The first keeps its name, so a book arriving never renames one already there. A name is cut to fit the 100 bytes with its qualifier.
  • Edition folders: each edition is a folder in the book's folder, named by its kind: Ebook, or Audiobook (§9). These are the words the apps show, in English on every device, like Book.md.
    • Editions of the same kind are told apart by qualifiers, in parentheses. For ebooks: the language, then the year, then the publisher, then a number. For audiobooks: the language, then the narrator (the first creator with role nrt), then the year, then a number. Numbers go in the order the editions were added, and by ID for those added at the same time, from 1: unlike books, every edition still sharing a name is qualified, so none keeps a plain name that a later one would take from it.
    • Each step qualifies every edition whose name is still shared, and only those, by its value there. A step where they all have the same value is skipped, and one without a value is told apart from those with one by having none: Ebook beside Ebook (en). For example, a book with English editions from 1965 and 2019 and a Dutch one has Ebook (en, 1965), Ebook (en, 2019), and Ebook (nl). One ebook and one audiobook are Ebook and Audiobook.
    • The primary edition gets no plain name of its own, so making another edition primary renames nothing. Adding an edition can qualify the folder of one already there: Ebook becomes Ebook (en) when a Dutch ebook arrives.
    • Languages are written as their codes (nl), years as the edition's publication year, and narrators and publishers by name. Values are compared as names are, ignoring case.
  • Edition files are {title} - {author}.epub, in the edition's folder, from the edition's own metadata, so the name says which book it is wherever the file goes. An edition in several files, such as an audiobook in MP3s, keeps its files' own names.
    • A name too long has its title cut to fit, keeping - {author} and the extension whole; when the author would take half the name or more, the whole name is cut instead.
    • A name another file has gets a qualifier in parentheses after the author, before the extension: the edition's language, then its year, then the first number from 2 that's free (Dune - Frank Herbert (en).epub).
    • "Half the name" is half of what's left of the 100 bytes after the qualifier and the extension. A part is cut first, then dots and spaces are trimmed from its ends.
  • An edition's own files are in its folder too: Edition.md holds its annotations (§6.3). A reader's own files beside the edition's file are left alone, except KOReader's .sdr folder, which is renamed with the file whose name it has.
  • Names work on FAT32, the strictest filesystem in use, on a Kobo, and on Windows, whose reserved names apply on any filesystem. Each part of a path is made from its metadata this way:
    • : becomes -; /, \, and | become -; " becomes '; and *, ?, <, >, and control characters are left out
    • runs of whitespace become one space, and dots and spaces are trimmed from both ends, so no name is hidden or ends in a dot
    • at most 100 bytes, cut at a character
    • a reserved name before any dot (CON, PRN, AUX, NUL, COM1–COM9, COM¹–COM³, LPT1–LPT9, or LPT¹–LPT³, in any case) gets a _ after it, before the dot: CON.txt becomes CON_.txt, within the 100 bytes
    • Unicode in NFC; never transliterated to ASCII
  • Names compare as the same when they are after NFC and then each character's Unicode lowercase mapping, taken one character at a time without context (not full case folding: ß stays ß, and a final Σ becomes σ, not ς). This is how names are compared everywhere in the format: folders and files for collisions, and collection names (§5.4).
  • Conformance examples: naming/names.json gives metadata and the names made from it, for other tools to test against.
  • Names follow the metadata. A device that applies edits (§3.3) also renames files and folders whose names no longer match. It waits until every edition of the book is downloaded and its edits are written, and logs each rename of an edition's folder or file as edition.updated. It never overwrites a file that already has the wanted name: the edition gets a qualifier instead.
  • Anyone can rename or move a book's folder or files. Books are found by the ID in their logs, and editions by their hash (§2.1), never by path, and names are put back in line when edits are next applied.

1.4 Shared work files

Some work is slow to make and the same whichever device makes it, so it's kept in the library for every device, rather than in each device's cache, such as an audiobook's alignment with its ebook (§9.2). Their files, in the book's .boeks/, are the exception to each device writing only its own files. The chapter of each says what its file holds; these rules are the same for all of them.

  • Any device writes it, whole: to a temporary file, then renamed over the old one, so a reader never sees half of one.
  • version is how its content is made. A device makes a file of an older version again, as what's in it no longer holds, and leaves one of a newer version alone: it neither uses nor overwrites it.
  • device and saved are the device that last saved it, and when, in milliseconds since the Unix epoch. A device that can only do the work in the background, now and then, as a phone or a tablet does, leaves a file to another device that saved it in the last 3 minutes, as that one is at it, and takes it up once it's been quiet that long: the two would otherwise redo each other's work. A device that does it whenever it's on, as a Mac does, never waits, and neither does work someone asked for.
  • A sync tool's conflict copy (§8.1) is merged into the file as its chapter says, and the merged file replaces the copies when it's next written. Where it has to choose between two that are as good as each other, it keeps the one saved first, so every device keeps the same one.
  • Keep what you don't know: fields a later version wrote are kept when the file is written again.