Skip to content
Back to search

eink-epub-builder

MarketplaceWorks with Claude CodeGitHub

The Pageturn plugin: interactive EPUB books for e-ink readers, with flipbook pages, page-turn questions and an e-ink simulator.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/vaseem00--eink-epub-builder/badge.svg)](/listings/vaseem00--eink-epub-builder)

HTML

<a href="/listings/vaseem00--eink-epub-builder"><img src="/api/listings/vaseem00--eink-epub-builder/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

After you [install](#install) the skill, ask your agent:

> Make an interactive EPUB that explains how photosynthesis works, for my Kobo Clara BW. About 30 screens, with flipbook diagrams and a checkpoint at the end.

> Turn these study notes into an e-ink book for my Kindle Paperwhite. Put each hard idea in a flipbook and each definition in a question.

> Build a pocket guide to Git branching for my Xteink X4, with page-turn questions.

Or run the engine yourself. It needs Node.js and nothing else:

git clone https://github.com/vaseem00/eink-epub-builder
cd eink-epub-builder
node skills/pageturn/engine/pageturn.mjs build examples/how-e-ink-works --preview

That writes `examples/how-e-ink-works/out/how-e-ink-works.epub` and the simulator page next to it.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 18 lines
  1. {
  2. "name": "eink-epub-builder",
  3. "owner": {
  4. "name": "vaseem00",
  5. "url": "https://github.com/vaseem00"
  6. },
  7. "description": "The Pageturn plugin: interactive EPUB books for e-ink readers, with flipbook pages, page-turn questions and an e-ink simulator.",
  8. "plugins": [
  9. {
  10. "name": "pageturn",
  11. "source": "./",
  12. "description": "Builds interactive EPUB books for e-ink readers. Animation becomes page turns: flipbook frames, answers that wait on the next page, checkpoints and scenarios. One book folder builds a validated EPUB 3 for Kindle, Kobo, PocketBook, Boox, Xteink and other readers.",
  13. "category": "productivity",
  14. "tags": ["epub", "e-ink", "ebook", "kindle", "kobo", "flipbook"],
  15. "skills": ["./skills/pageturn"]
  16. }
  17. ]
  18. }
README.md · README · 281 lines
  1. <div align="center">
  2. <img src="assets/logo.svg" alt="Pageturn" width="260">
  3. <h1>Interactive EPUB builder for e-ink readers</h1>
  4. <p><strong>An e-ink screen cannot animate. It can turn a page.<br>Pageturn turns your notes into a book of flipbook frames, hidden answers and diagrams, for the reader you own.</strong></p>
  5. <p>An open-source Agent Skill for Claude Code, Codex, GitHub Copilot, Cursor, Gemini CLI and other agents.<br>Kindle · Kobo · PocketBook · Boox · Xteink · reMarkable · Supernote · Nook · tolino</p>
  6. [![CI](https://github.com/vaseem00/eink-epub-builder/actions/workflows/ci.yml/badge.svg)](https://github.com/vaseem00/eink-epub-builder/actions/workflows/ci.yml)
  7. [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  8. [![Node.js 22 or later](https://img.shields.io/badge/node-%3E%3D22-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
  9. [![Zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](#requirements)
  10. [![EPUB 3](https://img.shields.io/badge/EPUB-3-86b817.svg)](https://www.w3.org/TR/epub-33/)
  11. [![Agent Skills](https://img.shields.io/badge/Agent%20Skills-compatible-6f42c1.svg)](https://agentskills.io/specification)
  12. [Live demo](https://vaseem00.github.io/eink-epub-builder/) · [See it work](#see-it-work) · [Quick start](#quick-start) · [Page types](#page-types) · [Readers](#readers) · [Install](#install) · [How it works](#how-it-works) · [Limits](#limits) · [FAQ](#faq)
  13. [![A simulated e-ink reader plays a four-page flipbook. In each page the same capsule drawing stays in place while the particles inside it change places and the pixel turns from white to black. The screen flashes between pages like a real e-ink refresh.](.github/assets/demo-flipbook.webp)](https://vaseem00.github.io/eink-epub-builder/#try)
  14. <sub>A flipbook from the example book, in the e-ink simulator that the engine writes. Four page turns, one drawing, one change at each turn. <a href="https://vaseem00.github.io/eink-epub-builder/#try">Open the live simulator</a>.</sub>
  15. </div>
  16. ## What it does
  17. E-ink readers are calm, sharp and easy on a battery. They also run no scripts, no video and no animation inside a book. So an "interactive ebook" made for a tablet shows as a wall of text on a Kindle or a Kobo.
  18. Pageturn uses the one animation that every e-reader has: **the page turn**.
  19. - A **flipbook** is a few pages with one picture. The drawing stays in place and one thing changes at each turn.
  20. - A **reveal** puts a question alone on a page. The answer waits on the next one.
  21. - A **checkpoint** asks a few questions, then shows the answers.
  22. - A **scenario** gives a situation with options, then the best path.
  23. You tell your agent the subject and your reader. The agent writes a small folder of text files. The Pageturn engine draws the figures, sizes each image for your screen, checks that each page fits, and writes a validated EPUB 3.
  24. ## See it work
  25. Every picture below is a capture of the real output: the example book [How an E Ink Screen Works](examples/how-e-ink-works), built by the engine and shown in its own simulator.
  26. <table>
  27. <tr>
  28. <td width="50%" valign="top">
  29. **Flipbook: a page turn is a movie frame**
  30. [![A flipbook on a pocket reader: the letter A, then B with a pale shadow of A, then a black flash, then a clean B.](.github/assets/demo-ghosting.webp)](https://vaseem00.github.io/eink-epub-builder/demo/how-e-ink-works.html#ghosting)
  31. Why an e-ink screen flashes, in four turns, on a 4.3 inch Xteink X4 Pro profile. One figure file holds all four frames, so they line up to the pixel.
  32. </td>
  33. <td width="50%" valign="top">
  34. **Reveal: the answer waits one turn away**
  35. [![A question stands alone on the screen of a simulated Kobo. After the page turn and a screen flash, the answer shows.](.github/assets/demo-reveal.webp)](https://vaseem00.github.io/eink-epub-builder/demo/how-e-ink-works.html#power)
  36. A question page and its answer page are two files in the EPUB. So the answer always starts on a new screen, on every reader.
  37. </td>
  38. </tr>
  39. <tr>
  40. <td width="50%" valign="top">
  41. **One folder, every reader**
  42. [![The same flipbook page on four simulated readers of different sizes: Xteink X4 Pro, Kobo Clara BW, Kindle Paperwhite and reMarkable 2.](.github/assets/readers.webp)](#readers)
  43. The same book builds for a 4.3 inch pocket reader and a 10 inch tablet. The engine sizes each image for the screen and warns when a label gets too small.
  44. </td>
  45. <td width="50%" valign="top">
  46. **It looks before it ships**
  47. [![A contact sheet of all 23 screens of the example book, as a 6 inch reader shows them.](.github/assets/sheet.webp)](#how-it-works)
  48. The `sheet` command shows every page as the reader shows it. A red frame marks a page that splits into two screens.
  49. </td>
  50. </tr>
  51. </table>
  52. **The simulator** is one HTML file. It has a reader switch, a full-refresh flash, a play button for flipbooks, and light and dark themes:
  53. [![The simulator page: a drawn e-ink reader on the left shows a flipbook frame, and a panel on the right has the reader switch, the text size, the refresh mode and the contents list.](.github/assets/simulator-light.webp)](https://vaseem00.github.io/eink-epub-builder/demo/how-e-ink-works.html)
  54. **Read the example on your own reader:** [any reader](https://vaseem00.github.io/eink-epub-builder/demo/how-e-ink-works.epub) · [Kobo Clara BW](https://vaseem00.github.io/eink-epub-builder/demo/how-e-ink-works-kobo-clara-bw.epub) · [Kindle Paperwhite](https://vaseem00.github.io/eink-epub-builder/demo/how-e-ink-works-kindle-paperwhite-2024.epub) (use Send to Kindle) · [Xteink X4 Pro](https://vaseem00.github.io/eink-epub-builder/demo/how-e-ink-works-xteink-x4-pro.epub). If you try one, please [tell us what you see](https://github.com/vaseem00/eink-epub-builder/issues/new/choose).
  55. ## Quick start
  56. After you [install](#install) the skill, ask your agent:
  57. > Make an interactive EPUB that explains how photosynthesis works, for my Kobo Clara BW. About 30 screens, with flipbook diagrams and a checkpoint at the end.
  58. > Turn these study notes into an e-ink book for my Kindle Paperwhite. Put each hard idea in a flipbook and each definition in a question.
  59. > Build a pocket guide to Git branching for my Xteink X4, with page-turn questions.
  60. Or run the engine yourself. It needs Node.js and nothing else:
  61. ```bash
  62. git clone https://github.com/vaseem00/eink-epub-builder
  63. cd eink-epub-builder
  64. node skills/pageturn/engine/pageturn.mjs build examples/how-e-ink-works --preview
  65. ```
  66. That writes `examples/how-e-ink-works/out/how-e-ink-works.epub` and the simulator page next to it.
  67. ## Page types
  68. A book is a folder of plain text. One `@` line starts a page, and one page is one screen.
  69. ```
  70. @flipbook pixel-flip | A pixel turns black | toc
  71. fig: pixel
  72. lead: Watch the particles in the capsule.
  73. 1: The plate below is positive. It holds the black particles down. You see white.
  74. 2: The plate below turns negative. Nothing has moved yet.
  75. 3: The plate now pushes the black particles up. They pass in the fluid.
  76. 4: Black is on top, so you see black. The power can go off now.
  77. @reveal power | Where does the power go?
  78. Q: You leave a page open for a week. How much power does the screen use to keep it there?
  79. A: Almost none. The particles stay in place without power.
  80. @quiz checkpoint | Checkpoint | toc
  81. ? What moves the particles?
  82. = The charge of the plate below the capsule.
  83. ```
  84. | Type | Pages it makes | Use it for |
  85. |---|---|---|
  86. | `@page` | 1 | One idea: a heading, text, a list, a box, one figure |
  87. | `@flipbook` | A lead-in, then 2 to 6 frames | A process, a motion, a before and after |
  88. | `@reveal` | Question, then answer | A flashcard that needs no app |
  89. | `@quiz` | Questions, then answers | A checkpoint at the end of a part |
  90. | `@scenario` | Situation with options, then the best path | A decision |
  91. | `@jump` | 1 | Links for touch screens |
  92. A figure is a short JSON file. A flipbook figure holds every frame: an item appears with `"show"`, goes with `"hide"`, and changes with `"steps"`.
  93. ```json
  94. {
  95. "size": [440, 300], "frames": 3,
  96. "items": [
  97. { "id": "frame", "type": "box", "at": [70, 20], "size": [300, 260], "stroke": 4 },
  98. { "id": "dot", "type": "circle", "at": [220, 150], "r": 20, "fill": "black",
  99. "steps": { "2": { "r": 60 }, "3": { "r": 115 } } }
  100. ]
  101. }
  102. ```
  103. Full reference: [the book format](skills/pageturn/engine/docs/format.md) and [figures](skills/pageturn/engine/docs/figures.md).
  104. ## Readers
  105. The engine has 33 profiles. Each one holds the screen in pixels, the size and the pixels per inch, and from these it derives the image scale, the largest figure canvas and the text size check. Run `node skills/pageturn/engine/pageturn.mjs devices` for the full table.
  106. | Family | Profiles | Opens EPUB | How the file gets there |
  107. |---|---|---|---|
  108. | Amazon Kindle | Kindle (2024), Paperwhite (2024), Colorsoft, Scribe (2024) | Amazon converts it | Send to Kindle: web, app or email |
  109. | Rakuten Kobo | Clara BW, Clara Colour, Libra Colour, Sage, Elipsa 2E | Yes | USB copy. `--kepub` selects Kobo's own engine |
  110. | PocketBook | Verse, Verse Pro, Era, InkPad 4, InkPad Color 3 | Yes | USB, PocketBook Cloud, Dropbox |
  111. | Onyx Boox | Palma, Go 6, Go Color 7, Page, Go 10.3, Note Air4 C | Yes | USB, BooxDrop, any Android reading app |
  112. | Xteink | X4, X4 Pro | Yes | Companion app or SD card; Wi-Fi upload with CrossPoint firmware |
  113. | reMarkable | reMarkable 2, Paper Pro | Yes | The reMarkable app |
  114. | Supernote | Nomad, Manta | Yes | USB or a cloud drive |
  115. | Nook, tolino | GlowLight 4, 4 Plus, shine, vision color | Yes | USB copy |
  116. | Any other | `universal`, `pocket`, `tablet` | | |
  117. Screen facts were checked on 20 November 2026. Each device has a grade (confirmed on the maker's page, secondary, or unverified) in [devices.json](skills/pageturn/engine/devices.json), and the sources are in [the readers guide](skills/pageturn/engine/docs/devices.md). Is a reader missing or wrong? [Open a reader report](https://github.com/vaseem00/eink-epub-builder/issues/new/choose).
  118. ## Install
  119. The repo is one Claude Code plugin named `pageturn` in a marketplace named `eink-epub-builder`. It is also a plain Agent Skills folder, so other agents can install it too.
  120. ### Claude Code
  121. ```
  122. /plugin marketplace add vaseem00/eink-epub-builder
  123. /plugin install pageturn@eink-epub-builder
  124. ```
  125. From a shell:
  126. ```
  127. claude plugin marketplace add vaseem00/eink-epub-builder
  128. claude plugin install pageturn@eink-epub-builder
  129. ```
  130. ### Claude Desktop and claude.ai
  131. Add the marketplace under **Customize > Plugins > Add marketplace**, with `vaseem00/eink-epub-builder` as the source, and install **Pageturn**. The code sandbox has no Chrome, so the engine writes SVG figures there. For JPEG figures and the simulator, run the build on your own computer.
  132. ### Any agent, with the skills CLI
  133. ```
  134. npx skills add vaseem00/eink-epub-builder # choose agents
  135. npx skills add vaseem00/eink-epub-builder -g -a claude-code -y # for your user, in Claude Code
  136. ```
  137. Use `-a codex`, `-a cursor`, `-a gemini-cli`, `-a github-copilot` or `-a opencode` for other agents.
  138. ### Codex, Copilot CLI, Gemini CLI
  139. ```
  140. codex plugin marketplace add vaseem00/eink-epub-builder
  141. copilot plugin install vaseem00/eink-epub-builder
  142. gemini extensions install https://github.com/vaseem00/eink-epub-builder
  143. ```
  144. ### Manual install
  145. Download the repo and copy the folder `skills/pageturn` into the skills folder of your agent, for example `~/.claude/skills/pageturn`.
  146. ### Requirements
  147. - **Node.js 22 or later.** The engine has no npm packages.
  148. - **Chrome, Chromium or Edge** on the computer, for JPEG and PNG figures, the page estimate, the contact sheet and the simulator. The engine starts it headless and finds it by itself; `PAGETURN_BROWSER` names another one. With no browser, the engine writes SVG figures and says so.
  149. - **Java and EPUBCheck**, only for the optional `validate` command.
  150. ## How it works
  151. ```
  152. your words -> agent writes a book folder -> pageturn check -> pageturn build -> .epub + simulator
  153. ```
  154. 1. **One page, one file.** Each page is its own XHTML file in the EPUB, so it starts on a new screen on every reader. Flipbook timing and hidden answers depend on this.
  155. 2. **Figures by construction.** The engine draws each figure from a list of boxes, arrows, dots and icons. All frames of a flipbook come from one file, so nothing shifts between two pages.
  156. 3. **Real pixels.** A headless browser turns each figure into pixels at the scale of the target screen. The engine then writes a baseline greyscale JPEG (or a 4-bit PNG) with its own encoder. Small readers can fail on progressive JPEG and on SVG.
  157. 4. **Checks with fixes.** 39 problem codes. Each names the place, the fault and the fix: a page with too many words, a label wider than its box, a line too thin for e-ink, a frame where nothing changes, a symbol that reader fonts lack.
  158. 5. **A page estimate from the real layout.** The engine lays out each page at the screen size, at a typical and a large text size, and counts the screens.
  159. 6. **A standard file.** EPUB 3 with a navigation document, an NCX for older readers, a drawn cover and accessibility metadata. The same folder gives the same bytes each time.
  160. | Command | Does |
  161. |---|---|
  162. | `new <id>` | Starts a book folder |
  163. | `devices` | Lists the reader profiles |
  164. | `check <book>` | Checks the rules and prints each problem with its fix |
  165. | `build <book> --strict --preview` | Writes the `.epub` and the simulator page |
  166. | `sheet <book>` | Writes a contact sheet of every page |
  167. | `figure <book> <name>` | Writes all frames of one figure side by side |
  168. | `validate <file.epub>` | Runs EPUBCheck |
  169. ## Limits
  170. - **Not tested on real devices.** The example book passes EPUBCheck 5.4.0 with 0 errors and 0 warnings, and it was viewed in the simulator. It was not loaded onto a Kindle, a Kobo or any other reader. The simulator is a browser page, not the firmware of a reader.
  171. - **The page count is an estimate.** The reader chooses the font and the margins.
  172. - **Kindle does not open EPUB files.** Amazon converts them through Send to Kindle, and the result is Amazon's.
  173. - **Xteink stock firmware may not show images inside an EPUB.** The CrossPoint firmware lists JPG and PNG support. Test one page first.
  174. - **Greyscale only.** Figures are grey on colour readers too.
  175. - **Links are a bonus.** Some readers have buttons only. The contents list always works.
  176. - **Device facts change.** Each profile has a date and a grade. Check the maker's page before you rely on one.
  177. ## FAQ
  178. **Can an e-ink reader show an animated EPUB?**
  179. No. E-ink readers run no scripts, video or animated images inside books. Pageturn gets a similar effect with page turns.
  180. **Is this a converter for existing ebooks?**
  181. No. Use Calibre for that. Pageturn makes new books that are designed for the page turn: study notes, courses, guides, manuals, interview preparation.
  182. **Do I need an AI agent?**
  183. No. The content is plain text and the figures are JSON, so you can write a book by hand and run the engine. The skill teaches an agent to do it for you.
  184. **Why JPEG and not SVG?**
  185. Kobo and Kindle handle SVG, but small readers such as the Xteink do not. Baseline greyscale JPEG is the format that the most readers show. Use `--images png` for smaller, sharper files where PNG works, or `--images svg`.
  186. **Does it work in other languages?**
  187. Yes. Set `language` in `book.json` and replace the built-in phrases with `labels`. The figure font covers Latin, Greek and Cyrillic text.
  188. ## Contribute
  189. The most useful help is a report from a real reader: load an example, and say what you see. See [CONTRIBUTING.md](CONTRIBUTING.md). Security reports: [SECURITY.md](SECURITY.md).
  190. ## Licence
  191. [MIT](LICENSE). The example book is CC BY 4.0. Kindle, Kobo, PocketBook, Boox, Xteink, reMarkable, Supernote, Nook and tolino are trademarks of their owners. This project is not affiliated with them. "E Ink" is a trademark of E Ink Corporation.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.