29. März 2026

Jaraco Reader – ein mobiler Linux-Reader für Markdown mit Mermaid und EPUB

Englische Version 

Wer auf Linux liest, kennt das Problem: Auf dem Desktop funktionieren viele Markdown- und EPUB-Reader wirklich gut, aber auf mobilen Geräten wird es schnell unbequem. Genau aus diesem Grund haben wir jaraco-reader entwickelt.

Die Idee war klar: Ein Reader, der auf postmarketOS sauber läuft, Markdown-Dokumente inklusive Mermaid-Diagrammen rendert und EPUB-Bücher einfach lesbar macht, ohne Desktop-Workflows auf dem Smartphone zu erzwingen.

Warum dieses Projekt entstanden ist

Bestehende Reader sind oft auf Desktop-Nutzung optimiert:

  • große Fensterlogik statt Touch-first-Bedienung
  • unklare Navigation auf kleineren Displays
  • schwache Unterstützung für technische Markdown-Inhalte mit Diagrammen

jaraco-reader wurde deshalb als pragmatische Mobile-Lösung gebaut. Ziel war nicht ein theoretischer Showcase, sondern ein Tool, mit dem man technische Dokumente und Bücher im Alltag wirklich lesen kann.

Die Kernmotivation in einem Satz:
Dieses Reader-Projekt wurde entwickelt, weil bestehende Markdown- und EPUB-Reader im Desktop-Modus hervorragend funktionieren, auf mobilen Geräten aber nicht so gut. Deshalb haben wir jaraco-reader gebaut, um Markdown-Dokumente mit Mermaid-Diagrammen und EPUB-Bücher deutlich einfacher lesen zu können.

Projektüberblick: Wie jaraco-reader arbeitet

Die Anwendung basiert auf GTK3 + WebKit2GTK 4.1 und nutzt Python als Laufzeit. Dadurch kombiniert sie native App-Steuerung mit robustem HTML/CSS-Rendering.

Was der Reader konkret leistet:

  • EPUB-Inhalte werden entpackt, Kapitel zusammengeführt und als durchgehende Leseseite angezeigt.
  • Markdown wird zu HTML konvertiert, inklusive fenced code blocks, Tabellen und Inhaltsstruktur.
  • Mermaid-Blöcke werden automatisch erkannt und als Diagramme gerendert.
  • Bilder und relative Assets werden korrekt aufgelöst.
  • Leseposition und Schriftgröße werden pro Buch gespeichert und beim nächsten Öffnen wiederhergestellt.

Wichtige Funktionen für mobile Nutzung

Damit der Reader auf einem Smartphone wirklich praktisch ist, wurden bewusst einfache, direkte Interaktionen umgesetzt:

  • Edge-Buttons für schnelles Vor/Zurück-Seiten
  • Go-to-Page-Dialog für direkten Sprung
  • Zoom in/Zoom out für anpassbare Lesbarkeit
  • Recent-Liste (bis zu 5 Bücher) beim Start
  • Tap auf leere Ansicht öffnet den Datei-Dialog
  • stabile Nutzung in Portrait und Landscape

Damit entsteht genau der Unterschied, der bei vielen Desktop-zentrierten Readern fehlt: kurze Wege, klare Touch-Bedienung und verlässliches Verhalten auf kleinen Displays.

Technischer Kern in Kurzform

Die Pipeline lässt sich kompakt so beschreiben:

  1. Datei öffnen (.epub, .md, .markdown)
  2. Inhalt normalisieren (EPUB-Parsing oder Markdown-Rendering)
  3. HTML in WebKit2.WebView laden
  4. Scroll-Position periodisch erfassen und als Fraction speichern
  5. Beim Wiederöffnen Position + Zoom reproduzieren

Zusätzlich wird EPUB-Content in ~/.cache/jaraco-reader/ abgelegt, damit Assets lokal sauber verfügbar sind. Zustände wie recent, last_book, fraction und font_size landen in ~/.config/jaraco-reader/positions.json.

Warum das auf postmarketOS gut passt

postmarketOS gibt uns ein echtes Alpine-Linux-System auf dem Smartphone. Das bedeutet:

  • nachvollziehbare Paketierung mit APKBUILD + abuild
  • direkte Installation und Tests auf dem Gerät
  • keine proprietäre Sonderplattform für einen einfachen Reader

jaraco-reader bleibt dadurch bewusst nah an klassischer Linux-Entwicklung: transparent, paketierbar und wartbar.

Fazit

jaraco-reader ist aus einem konkreten Pain Point entstanden: Desktop-Reader sind stark, mobile Lesbarkeit technischer Inhalte ist oft schwach. Mit GTK, WebKit2GTK, Markdown-Rendering und Mermaid-Unterstützung liefert das Projekt genau die Funktionen, die auf mobilen Linux-Geräten fehlen.

Für uns ist das zentrale Ergebnis nicht nur „ein weiterer Reader“, sondern ein praxisnahes Werkzeug, das Markdown-Dokumente mit Diagrammen und EPUB-Bücher auf postmarketOS deutlich einfacher lesbar macht.

Warum maßgeschneiderte Software wichtig ist

Viele Anwendungen heute sind sehr generalistisch. Sie decken alles irgendwie ab, machen im Alltag aber oft zu viel auf einmal oder an entscheidenden Stellen zu wenig. Genau daraus entstehen Reibungsverluste: mehr Klicks, mehr Kompromisse, weniger Fokus.

Spezifische Tools, die exakt deinen Workflow unterstützen, sind heute erreichbar. Wenn du vor ähnlichen Problemen stehst und dich fragst, ob es nicht eine passgenauere Lösung gibt: Kontaktiere uns. Wir unterstützen dich gerne.

Appendix: Relevante Befehle

  • ./app/jaraco-reader /path/to/book.epub
    Startet den Reader direkt mit einer EPUB-Datei.
  • ./app/jaraco-reader /path/to/doc.md
    Öffnet ein Markdown-Dokument mit HTML-Rendering und Mermaid-Support.
  • abuild -F
    Baut das APK-Paket aus APKBUILD.
  • apk add --allow-untrusted /home/user/packages/projects/aarch64/jaraco-reader-<version>.apk
    Installiert das gebaute Paket auf dem Gerät.

Kopiere die nachfolgende Replication Spec, um das Projekt nachzubauen.

Jaraco Reader Replication Spec

1. Objective

Replicate jaraco-reader, a GTK-based mobile-friendly reader for postmarketOS/Alpine Linux that:

  • Opens .epub, .md, and .markdown files.
  • Renders EPUB and Markdown content in a WebKit view.
  • Supports Mermaid diagrams in Markdown documents.
  • Preserves reading position and font size per book.
  • Provides touch-friendly navigation for mobile devices.

2. Scope

In scope:

  • Single-process Python application (app/jaraco-reader).
  • GTK3 + WebKit2GTK UI.
  • EPUB parsing + extraction to cache.
  • Markdown-to-HTML rendering with Mermaid integration.
  • Local state persistence (positions.json).
  • Alpine APK packaging via APKBUILD.
  • Desktop integration (.desktop, appdata, icon, post-install defaults).

Out of scope:

  • Cloud sync.
  • Annotation/highlight features.
  • DRM-protected EPUB support.
  • Network content fetching.

3. Target Environment

  • OS: postmarketOS (preferred) or Alpine Linux.
  • Runtime:
    • python3
    • py3-gobject3
    • py3-markdown
    • gtk+3.0
    • webkit2gtk-4.1
    • adwaita-icon-theme
  • Build tooling:
    • abuild
    • alpine-sdk

Install prerequisites:

apk add abuild alpine-sdk python3 py3-gobject3 py3-markdown gtk+3.0 webkit2gtk-4.1 adwaita-icon-theme

4. Source Layout

Required files and purpose:

  • app/jaraco-reader: Main executable Python app.
  • data/mermaid.min.js: Bundled Mermaid runtime loaded by Markdown renderer.
  • data/io.jaraco.Reader.desktop: Desktop launcher + MIME registration.
  • data/io.jaraco.Reader.appdata.xml: Software metadata.
  • data/io.jaraco.Reader.svg: App icon.
  • APKBUILD: Alpine packaging recipe.
  • jaraco-reader.post-install: Post-install MIME defaults hook.

4.1 Mermaid JS Download Instructions

jaraco-reader expects Mermaid at data/mermaid.min.js during build, which is then installed to:

  • /usr/share/jaraco-reader/mermaid.min.js

Recommended source:

  • jsDelivr CDN (Mermaid v10 distribution):
    • https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js

Download command (run from repository root):

curl -L -o data/mermaid.min.js "https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"

Optional verification:

ls -lh data/mermaid.min.js

Notes:

  • Keep the filename exactly mermaid.min.js.
  • If this file is missing, Markdown still opens, but Mermaid diagrams will not render.

5. Functional Requirements

5.1 File Open and Rendering

  • Accept optional CLI path argument.
  • If no file is provided:
    • Attempt to open last-read book.
    • Else show prompt with recent books and browse option.
  • .epub:
    • Read META-INF/container.xml, find OPF rootfile.
    • Parse manifest/spine.
    • Extract archive to cache directory.
    • Merge chapter bodies into a single HTML document.
    • Resolve relative links/images to file:// absolute paths.
  • .md / .markdown:
    • Convert Markdown to HTML with extensions:
      • fenced_code
      • tables
      • toc
      • sane_lists
    • Convert mermaid fenced blocks to <div class="mermaid">....
    • Inject Mermaid JS (/usr/share/jaraco-reader/mermaid.min.js) if present.

5.2 Reading UX

  • Header controls:
    • Open file
    • Zoom out
    • Zoom in
    • Go to page
  • Overlay edge buttons:
    • Previous page
    • Next page
  • Page scroll movement per action: ~0.9 * viewport height.
  • Click/tap behavior:
    • Empty state click opens file prompt.

5.3 Persistence

  • Config path: ~/.config/jaraco-reader/positions.json.
  • Cache path: ~/.cache/jaraco-reader/.
  • Persist per book:
    • fraction (scroll position ratio)
    • font_size
  • Persist global:
    • _last_book
    • _recent (max 5 entries)
  • Restore fraction and font_size on reopen.

6. Non-Functional Requirements

  • Mobile-friendly interaction on small screens.
  • No network dependency for rendering Mermaid (local JS file).
  • Works in portrait and landscape.
  • Robust against malformed EPUB files (fail gracefully with visible error in title area).

7. Implementation Notes

  • GI versions:
    • Gtk = 3.0
    • WebKit2 = 4.1
    • Gdk = 3.0
  • Keep JavaScript enabled in WebKit settings.
  • Poll scroll state on timer (~1000ms) and debounce config writes (~500ms).
  • Use atomic config writes (tmp + os.replace).
  • Use SHA-256(path) prefix as EPUB extraction directory key.

8. Packaging Requirements (APK)

APKBUILD must:

  • Install executable to /usr/bin/jaraco-reader.
  • Install desktop file to /usr/share/applications/io.jaraco.Reader.desktop.
  • Install appdata to /usr/share/metainfo/io.jaraco.Reader.appdata.xml.
  • Install icon to /usr/share/icons/hicolor/scalable/apps/io.jaraco.Reader.svg.
  • Install Mermaid JS to /usr/share/jaraco-reader/mermaid.min.js.
  • Declare runtime dependencies listed in section 3.

Post-install (jaraco-reader.post-install) must:

  • Register default app for:
    • application/epub+zip
    • text/markdown
    • text/x-markdown
  • Run update-desktop-database when available.

9. Build and Install Procedure

Build:

abuild -F

Expected package output path:

/home/user/packages/projects/aarch64/

Install:

apk add --allow-untrusted /home/user/packages/projects/aarch64/jaraco-reader-<version>-r<rel>.apk

Run:

jaraco-reader /path/to/book.epub
jaraco-reader /path/to/doc.md

10. Verification Checklist

  1. Open EPUB with images; confirm content renders end-to-end.
  2. Open Markdown with Mermaid fenced block; confirm diagram renders.
  3. Change zoom, close app, reopen same file; confirm zoom restored.
  4. Scroll mid-document, close/reopen; confirm position restored.
  5. Open >5 files over time; confirm recent list is capped to 5.
  6. Test page jump + edge navigation controls.
  7. Start without argument; confirm recent/browse startup dialog behavior.
  8. Confirm app is available from launcher and opens associated .epub/.md.

11. Acceptance Criteria

Replication is successful when:

  • All functional requirements in section 5 pass.
  • Packaging and installation steps in section 9 produce installable APK.
  • Verification checklist in section 10 passes on target device.
jaraco-software-engineers-verlauf-cta
jaraco-logo

Kontaktieren Sie uns noch heute und lassen Sie uns gemeinsam Ihre Softwarelösungen entwickeln!