# Jaraco Reader – A Mobile Linux Reader for Markdown with Mermaid and EPUB Anyone who reads on Linux knows the problem: Many Markdown and EPUB readers work really well on the desktop, but they quickly become cumbersome on mobile devices. This is exactly why we developed `jaraco-reader`. The idea was clear: A reader that runs cleanly on postmarketOS, renders Markdown documents including Mermaid diagrams, and makes EPUB books easily readable without forcing desktop workflows on smartphones. ## Why This Project Came to Be Existing readers are often optimized for desktop use: - Large window logic instead of touch-first operation - Unclear navigation on smaller displays - Weak support for technical Markdown content with diagrams `jaraco-reader` was therefore built as a pragmatic mobile solution. The goal was not a theoretical showcase, but a tool that allows you to actually read technical documents and books in everyday life. The core motivation in one sentence: This reader project was developed because existing Markdown and EPUB readers work excellently in desktop mode, but not as well on mobile devices. That's why we built `jaraco-reader` to make Markdown documents with Mermaid diagrams and EPUB books significantly easier to read. ## Project Overview: How `jaraco-reader` Works The application is based on GTK3 + WebKit2GTK 4.1 and uses Python as the runtime. This combines native app control with robust HTML/CSS rendering. What the reader specifically does: - EPUB content is unpacked, chapters are merged, and displayed as a continuous reading page. - Markdown is converted to HTML, including fenced code blocks, tables, and content structure. - Mermaid blocks are automatically detected and rendered as diagrams. - Images and relative assets are resolved correctly. - Reading position and font size are saved per book and restored when reopened. ## Important Features for Mobile Use To make the reader truly practical on a smartphone, simple, direct interactions were deliberately implemented: - Edge buttons for quick page forward/backward - Go-to-page dialog for direct jumps - Zoom in/out for adjustable readability - Recent list (up to 5 books) at startup - Tap on empty view opens the file dialog - Stable use in portrait and landscape This creates exactly the difference that many desktop-centric readers lack: short paths, clear touch operation, and reliable behavior on small displays. ## Technical Core in Brief The pipeline can be described compactly as follows: 1. Open file (`.epub`, `.md`, `.markdown`) 2. Normalize content (EPUB parsing or Markdown rendering) 3. Load HTML in `WebKit2.WebView` 4. Periodically capture scroll position and save as fraction 5. Reproduce position + zoom when reopened Additionally, EPUB content is stored in `~/.cache/jaraco-reader/` so that assets are cleanly available locally. States like `recent`, `last_book`, `fraction`, and `font_size` are stored in `~/.config/jaraco-reader/positions.json`. ## Why This Fits Well with postmarketOS postmarketOS gives us a real Alpine Linux system on the smartphone. This means: - Traceable packaging with `APKBUILD` + `abuild` - Direct installation and testing on the device - No proprietary special platform for a simple reader `jaraco-reader` thus remains deliberately close to classic Linux development: transparent, packageable, and maintainable. ## Conclusion `jaraco-reader` emerged from a concrete pain point: Desktop readers are strong, but mobile readability of technical content is often weak. With GTK, WebKit2GTK, Markdown rendering, and Mermaid support, the project delivers exactly the features that are missing on mobile Linux devices. For us, the central result is not just "another reader," but a practical tool that makes Markdown documents with diagrams and EPUB books significantly easier to read on postmarketOS. ## Why Custom Software Matters Many applications today are very generic. They cover everything somehow, but in everyday use, they often do too much at once or too little at crucial points. This is exactly where friction losses arise: more clicks, more compromises, less focus. Specific tools that support exactly your workflow are achievable today. If you face similar problems and wonder if there isn't a more tailored solution: Contact us. We'll be happy to support you. ## Appendix: Relevant Commands - `./app/jaraco-reader /path/to/book.epub` Starts the reader directly with an EPUB file. - `./app/jaraco-reader /path/to/doc.md` Opens a Markdown document with HTML rendering and Mermaid support. - `abuild -F` Builds the APK package from `APKBUILD`. - `apk add --allow-untrusted /home/user/packages/projects/aarch64/jaraco-reader-.apk` Installs the built package on the device.