bookends.koplugin

Tokens are placeholders that expand to live values. Type % followed by a name, or use the Tokens button in the line editor.

All tokens below use the v5 descriptive vocabulary. Older one-letter tokens like %A or %J still work — your existing presets don’t need changing — but when you open an existing preset in the editor, they’ll be rewritten to the new names so you can see what they mean at a glance.

Metadata

Genres. %genre and %genres read the book’s Keywords field, the one KOReader shows under Book information and lets you edit there. Keywords separated by commas, semicolons, pipes or line breaks each count as a genre, and a spaced slash splits a subject heading, so Fiction / Fantasy reads as two. A slash with no spaces around it stays part of the tag. If a book has no keywords both tokens are empty, so [if:genres] hides the line rather than leaving a gap.

Calibre columns. If your library is managed by Calibre, %calibre{name} shows any column from it, using the column’s lookup name: a custom column #mood renders with %calibre{mood}. Text, list, number, date, yes/no and multi-value columns all work; long-text (“Comments”) columns are skipped, being the wrong shape for a status line. Three standard fields come through the same way: %calibre{pubdate} (the year), %calibre{publisher} and %calibre{rating}. Conditionals work too, e.g. [if:calibre{mood}="cosy"]Cosy read[/if].

This reads the metadata.calibre file Calibre writes into your KOReader home folder (the one set under Settings > Home folder) or the folder above it, and reads nothing at all unless one of your lines actually uses the token. If your books live elsewhere, or you copy files across by hand rather than sending them from Calibre, there is no such file and these tokens stay empty. A book with no value for a column shows nothing at all, so [if:calibre{pubdate}]%calibre{pubdate}[/if] hides itself on books that have no date. One caveat worth knowing: KOReader’s own wireless Calibre sync rewrites that file and permanently drops custom columns from it. A small calibre.bookshelf.json saved alongside preserves them and is shared with Bookshelf if you run both plugins.

Author and last-digit families, typed manually. %author_1 through %author_5 pick a specific author by position, the same way %author_2 does. And %page_num_lastdigit, %page_count_lastdigit, %pages_left_lastdigit, %chap_read_lastdigit, %chap_pages_lastdigit and %chap_pages_left_lastdigit expose just the final digit of their counter, for languages whose grammar branches on it (Hungarian vowel harmony, for instance: [if:page_num_lastdigit=3]). Neither family appears in the token picker.

%file_num / %file_count count the document files in the folder the open book sits in, ordered the same way the file manager shows them (your sort by and reverse sorting settings both apply). Mainly useful for comics and manga kept as one file per chapter, where the page and chapter tokens can only describe the chapter you’re in: File %file_num/%file_count → File 5/10. The folder is read once per book opened, and only if one of these two tokens is in your preset.

Page / Progress

Chapter progress at a TOC depth. Like %chap_title_N, the chapter progress tokens take a depth suffix N (1-9): %chap_pct_N, %chap_pct_left_N, %chap_read_N, %chap_pages_N, %chap_pages_left_N. Without a suffix they track the deepest chapter covering the page; with %chap_read_1 etc. they measure against the top-level chapter instead. Useful for books with a very fine TOC (a heading every few paragraphs), where pairing %chap_title_1 with a plain %chap_read would show the top-level title next to a tiny sub-chapter’s length. N deeper than the book’s TOC collapses to the deepest level. Typed manually — not in the token picker.

Time / Date

Custom date and time formats use %datetime{spec}, which accepts any strftime spec. Example: %datetime{%d %B} → “23 April”. For the common cases, use the fixed tokens like %date and %time. The same brace syntax also works on %chap_time_left_eta, %book_time_left_eta, %book_finish_date, and the depth variant %chap_time_left_N_eta.

Reading

Time left at a TOC depth. %chap_time_left_N and %chap_time_left_N_eta{spec} scope the remaining-time estimate to the level-N chapter, the same way the progress tokens above do. Both need the statistics plugin and render empty without it.

Duration formatting follows KOReader, not Bookends. Every duration above is rendered by KOReader’s own formatter, so the style comes from Settings → Device → Time and date → Duration format. The default is classic, which gives 7:36; choose letters for 7h 36m, or modern for a 7h36' style. The examples in this table are shown in the letters style. Bookends deliberately does not override the choice, so durations match the rest of your reader.

Device

Page tokens respect stable page numbers and hidden flows (non-linear EPUB content). All reading-time and pages-read tokens (session, today, lifetime) come from the statistics plugin and are skip-aware — pages flicked through faster than the dwell threshold (default 5s) don’t count. Session counters reset each time you open the book or wake from suspend.

Inline progress bar

Add a %bar token to any line to render an inline progress bar. The bar auto-fills available space and can be mixed with text (e.g. %book_pct %bar). Use the bar controls in the line editor to set:

• Type — Chapter, Book, Book+ (top-level ticks), Book++ (top 2 level ticks)
• Style — Border, Solid, Round, Metro, Wave, Radial, Hollow

Show or hide content based on device state, reading progress, time, and more using [if:condition]...[/if] blocks with optional [else]:

[if:wifi=on]📶[/if]
[if:batt<20]LOW %batt[/if]
[if:charging=yes]⚡[/if] %batt
[if:page=odd]%title[else]%chap_title[/if]
[if:book_pct>90]Almost done![/if]
[if:time>22:00]Late night reading![/if]
[if:day=Sat]Weekend![else]%weekday_short[/if]
[if:chap_title_2]%chap_title_2[else]%chap_title_1[/if]
[if:not series]Standalone[/if]
[if:day=Sat or day=Sun]Weekend[/if]
[if:format=PDF]%page_num / %page_count[/if]
[if:chap_title_1!=@title]%chap_title_1 · [/if]
[if:batt!=100]charging…[/if]

Comparison operators: = (equals), != (not equals), < (less than), > (greater than), <= (less than or equal), >= (greater than or equal). Boolean operators: and, or, not, with parens () for grouping. Conditionals can be nested to any depth — [if:A][if:B]…[/if][/if] — and compose with [else].

String predicates evaluate as falsy when the string is empty, so [if:not series] means “book isn’t in a series” and [if:chap_title_2] means “we’re in a sub-chapter at depth 2”. For exact-match comparisons, wrap multi-word values in double quotes — e.g. [if:author="J.R.R. Tolkien"] or [if:title!="Untitled"].

Keep the separating space inside the block. A hidden [if:…][/if] is replaced by nothing at all, so any space you leave outside it survives into the output and shows up as a stray indent — visible as uneven margins on a centred or right-aligned position. Write [if:chap_time_left_h>0]%chap_time_left_h hr(s) [/if]%chap_time_left_m min(s) (space before [/if]), not [if:…]%chap_time_left_h hr(s)[/if] %chap_time_left_m min(s).

Legacy predicate names (chapters, chapter_pct, chapter_title, percent, pages) still evaluate — they’re aliased to their v5 equivalents automatically.

The right-hand side of a comparison can reference another state value with @. For example, [if:chap_title_1!=@title] is true when the depth-1 chapter title differs from the book title — useful for hiding duplicate headings when a book’s only top-level TOC entry is the title itself. Any @key that doesn’t exist in the state table resolves to an empty string.

Conditions evaluate live — the charging icon appears the moment you plug in, the wifi icon vanishes when you disconnect. The token picker has a dedicated If/Else conditional tokens submenu with syntax help, examples, and a complete reference.

Up to 8 independent progress bars rendered as dedicated layers behind text. Configure via Full width progress bars in the Bookends menu.

• Anchor — Top, Bottom, Left (vertical), Right (vertical)
• Fill direction — Left to right, Right to left, Top to bottom, Bottom to top
• Style — Solid, Bordered, Rounded, Metro, Wave, Radial, Radial hollow
• Chapter ticks — Off, Top level, Top 2 levels (book type only)
• Thickness and margins with real-time nudge adjustment
• Position relative to line text: keep a top or bottom bar a set distance from the lines of text on that side, instead of a fixed distance from the screen edge. Text grows and shrinks with the screen, so a bar placed just under a header on one device can land inside the text, or out on the page, on another; this keeps it with the text. Adjust margins then sets that distance, and negative values move the bar in towards the text

Progress on EPUB documents updates smoothly per screen turn using pixel-level position tracking. Chapter tick marks vary in thickness by TOC depth.

The Symbols button in the line editor opens a picker with categorised glyphs from the Nerd Fonts set (bundled with KOReader). Categories include:

• Dynamic — Battery and Wi-Fi icons that change with device state
• Device — Lightbulb, sun, moon, power, Wi-Fi, cloud, memory chip
• Reading — Book, bookmarks, eye, flag, bar chart, tachometer, sliders
• Time — Clock, stopwatch, watch, hourglass, calendar
• Status — Check, cross, info, warning, cog
• Symbols — Sun, warmth, card suits, stars, daggers, pilcrow, copyright, numero, check/cross marks
• Arrows — Directional arrows, triangles, angle brackets
• Progress blocks — Block-fill glyphs for hand-built progress strings
• Separators — Vertical bar, bullets, dots, dashes, slashes

Per-line styling

Each line has its own style controls in the editor dialog:

• Style — Cycles through: Regular, Bold, Italic, Bold Italic
• Uppercase — Toggle uppercase rendering
• Size — Font size in pixels (defaults to global setting, affected by font scale)
• Font — Choose from the full CRE font list
• Nudge — Fine-tune vertical and horizontal position of individual lines
• Page filter — Show on all pages, odd pages only, or even pages only

Italic uses automatic font variant detection — searches installed fonts for matching italic variants.

Inline formatting

Use BBCode-style tags to format parts of a line independently:

Tags can be nested: [b][i]bold italic[/i][/b]. Tags must be properly nested — overlapping tags like [b][i]...[/b][/i] render as literal text. Unclosed tags also render as literal text.

Tags override the line’s per-line style. If a line is set to Bold, [i]text[/i] renders that segment as italic (not bold italic). Use [b][i]...[/i][/b] for explicit bold italic.

• Auto-hide — Lines where all tokens resolve to empty or zero are automatically hidden
• Token width limits — Append {N} to any token to cap its width at N pixels: %chap_title{200} - %chap_read/%chap_pages truncates the chapter title with ellipsis if it exceeds 200 pixels. Works with %bar{400} to set a fixed bar width instead of auto-fill.
• Elastic gap. %spacer absorbs the leftover width of a line, pushing everything after it to the far edge: %author%spacer%book_pct puts the author hard left and the percentage hard right on one line. A line can only stretch in one place, so if it also has a %bar the bar takes the space and the spacer is dropped; a second %spacer is dropped too.
• Delimited tokens — A token name runs until the next non-letter, so text placed straight after it is read as part of the name. Wrap the name in angle brackets to butt text directly against it: %<book_time_left_h>h%<book_time_left_m>m → 4h40m. Width limits still work inside: %<author{200}>.
• Pluralisation — Write %highlights highlight(s) and it becomes 1 highlight or 3 highlights
• Odd/even pages — Set any line to appear on all pages, odd pages only, or even pages only
• Auto-refresh — Clock and other dynamic tokens update every 60 seconds

Smart ellipsis

When text would overlap between positions on the same row, Bookends automatically truncates with ellipsis. Center positions get priority by default — left and right text is truncated first. Enable Prioritise left/right and truncate long center text to reverse this.

Margins

Bookends uses a three-layer positioning system:

1. Global margins (top/bottom/left/right) — Set in Settings > Adjust margins with real-time preview
2. Per-position extra margins — Additional offset for individual regions
3. Per-line nudges — Pixel-level fine-tuning in the line editor

Managing lines

• Tap a line entry in a position’s submenu to edit it
• Tap Add line to add a new line to the position
• Long-press a line entry for options: Move up, Move down, Move to another position, or Delete
• Saving an empty line automatically removes it
• The editor shows a live preview of your format string as you type

The Bookends menu separates global settings (apply everywhere, never saved with presets) from per-preset styling (saved into the active preset and switched when you swap presets).

Global — Bookends → Bookends settings

Per-preset — Bookends → Preset (active preset name)

Bookshelf’s status line

If you also run Bookshelf, it can put its own status line across the top of the reader. Bookshelf draws it and Bookshelf owns the switch (menu > Settings > Also show status line in reader), so it works whether or not Bookends is installed.

All Bookends does is get out of the way: your top-row regions, and any top-anchored progress bar, all shift down by the height of the strip, so they keep the spacing you set between them. Nothing to configure here.

Disabling the stock status bar

For the best experience, disable KOReader’s built-in status bar via Bookends → Bookends settings → Disable stock status bar. This:

• Reduces e-ink flicker — Bookends no longer needs to repaint over the stock footer, eliminating extra screen refreshes on page turns
• Frees screen space — The stock footer’s reserved area is returned to the reading area
• Avoids duplication — All stock status bar features (time, battery, progress, pages, etc.) are available as Bookends tokens

Gesture support

Assign Bookends: toggle visibility, Bookends: cycle preset, Bookends: set visibility, or Bookends: open preset library to any gesture via KOReader’s Gesture manager > Reader to show/hide overlays or swap presets with a tap, swipe, or multi-finger gesture.

Bookends’ font picker includes KOReader’s font-family slots: UI font, Serif, Sans-serif, Monospace, Cursive, and Fantasy. Pick a family instead of a specific font, and overlays will use whichever font you have mapped to that slot in KOReader Settings › Font › Font-family fonts. This keeps overlay appearance consistent with your document font and makes presets portable across devices — someone sharing a preset that picks “Serif” will have it rendered in your serif, not theirs.

If a family slot isn’t mapped in KOReader, the overlay falls back to your KOReader UI font. That’s the same behaviour KOReader itself uses. If you see overlay text rendering in the UI font when you expected something else, check your KOReader Font-family fonts menu and set a mapping for that family.

Bookends covers the same information as KOReader’s built-in status bar, often with finer granularity. This table maps each stock footer item to the bookends token(s) that produce the same information.

Bookends’ six-zone positioning model replaces stock’s dynamic_filler layout. Stock’s additional_content plugin hook is exposed as the %plugin_content token (see Device tokens above), so plugins like kobo.koplugin and readtimer.koplugin keep working when the stock bar is disabled.