← Folio Docs

User Guide

How to install Folio, import books, organize your library, and read comfortably. Covers the main features without assuming you're already familiar with the app.

Getting Started

System requirements

No extra runtimes or dependencies needed. The installer is self-contained.

Downloading

Go to the GitHub Releases page and grab the package for your OS:

• macOS: .dmg
• Windows: .msi
• Linux: .AppImage or .deb

Installing

macOS: Open the .dmg, drag Folio into your Applications folder, then double-click to launch it.

xattr -cr /Applications/Folio.app

Windows: Run the .msi installer and follow the prompts.

Linux (AppImage): Make the file executable (chmod +x Folio.AppImage), then run it.

Linux (.deb): Run sudo dpkg -i folio.deb.

First launch

The first time you open the app, you’ll see an empty library with a prompt to import your first book. Your data stays on your machine — nothing is sent to the cloud.

Importing Books

Supported formats

How to import

Click the + Add books button in the top-right corner to open the import menu:

• Add files: Opens a file picker for one or more files in any supported format.
• Import folder: Scans an entire directory for supported files and imports them in batch, with a progress indicator.
• Import from URL: Paste a direct link to an EPUB, PDF, CBZ, or CBR file. Folio downloads and imports it.

Drag and drop: You can also drag files from Finder or File Explorer directly onto the library window. A “Drop to import” overlay appears. Release to import them.

When you import a book, Folio copies the file into its own managed library folder (default ~/Documents/folio/). The original file is not modified or moved. Duplicate files are detected by content hash and skipped automatically.

Viewing Your Books

Books are shown as a cover grid. Each card displays the cover image, title, author, star rating (if set), a progress percentage badge, and a format badge for non-EPUB books.

In the full library view, a “Continue Reading” row at the top shows your most recently read books, and a “Discover” row shows popular titles from your configured OPDS catalogs. Both sections are hidden when viewing a collection or series, so you see only the relevant books.

Searching and Filtering

• Search: Type in the search bar to filter by title or author. Results update as you type.
• Format filter: Filter by All, EPUB, PDF, CBZ, or CBR.
• Status filter: Filter by All, Unread, In Progress, or Finished.
• Rating filter: Filter by minimum star rating (1+ through 5 stars).
• Sorting: Sort by date added, title, author, last read, progress, rating, or series — ascending or descending.
• Source filter: Filter by All, Imported, or Linked books.

All filters combine, so you can search for “asimov” within “epub” books that are “in progress.”

Editing and Removing Books

Hover over a book card to reveal action buttons:

• Edit: Opens a dialog to change the title, author, cover image, and tags.
• Delete: Removes the book from your library (with a confirmation prompt).

Bulk Actions

When you need to act on several books at once, click the selection icon in the toolbar (the grid icon next to the import button). This puts the library into selection mode:

• Click book cards to select or deselect them. A checkbox appears on each card.
• A floating action bar shows at the bottom with the selection count.
• Select all / Deselect all toggles between selecting every visible book or clearing the selection.
• Delete removes all selected books (with a confirmation prompt).
• Cancel exits selection mode.

Drag-and-drop is disabled while in selection mode to prevent accidental imports.

Linked Books

By default, importing a book copies the file into Folio’s managed library folder. With linked books, you can keep the file in its original location and still get full features: progress tracking, bookmarks, highlights, metadata, and collections.

• Default import mode: In Settings > Library, toggle the default between “Copy to library” and “Link in place”. Applies to file picker, folder import, and drag-and-drop.
• Visual badge: Linked books show an external-link icon on their card to distinguish them from library-local books.
• Library filter: Filter by All, Imported, or Linked.
• Missing files: If the original file becomes unavailable (drive ejected, path moved), Folio shows an error toast with an option to remove the entry.
• Copy to library: You can internalize a linked book later via the “Copy to library” action in the Edit Book dialog.

Remote backups and ZIP exports skip linked book files (metadata is still included).

Manual Collections

Collections let you organize books into groups. Open the collections sidebar by clicking the collections icon or pressing C.

Create a collection, then drag book cards onto it to add them. You can remove books from a manual collection via the book card’s context actions.

Automated Collections

Define rules and Folio populates the collection automatically. Available rule types:

Multiple rules are combined with AND logic — a book must match all rules to appear in the collection.

Collection options

• Custom icon (choose from preset emoji)
• Custom color (choose from preset palette)
• Export as Markdown
• Delete collection

Series Grouping

Books with series metadata are automatically grouped in two ways:

• Sidebar: A “Series” section appears below collections, showing each series with its book count. Click a series to filter the library to just those books, sorted by volume order.
• Sort by Series: Select the “Series” sort option in the library toolbar. Books are grouped under series headers, sorted by volume within each group. Books without series data appear at the bottom.

Series data comes from book file metadata (EPUB/CBZ). You can also set or edit series info manually via the edit dialog on any book.

Reading EPUBs

Click any book card to open it. If you’ve read it before, Folio picks up where you left off — same chapter, same scroll position.

Folio offers two reading modes for EPUBs, selectable in Settings > Page Layout:

Paginated mode (default)

Read one chapter at a time. Navigate with the Previous/Next buttons at the bottom, press the left/right arrow keys, or pick a chapter from the Table of Contents. Floating chapter arrows appear on the left/right edges when you scroll past the bottom navigation bar.

Continuous scroll mode

All chapters are loaded and rendered as a single scrollable page with chapter title dividers between them. Scroll naturally through the entire book. The Table of Contents still works — clicking a chapter scrolls directly to it.

Common to both modes

• Table of Contents: Click the list icon in the header or press T. The sidebar shows a searchable, hierarchical chapter list with the current chapter highlighted.
• Focus mode: Press D to hide all UI and read distraction-free. Move the mouse to the top or bottom edge to temporarily reveal controls.
• Progress tracking: Your reading position is saved automatically and restored when you reopen the book.
• Time-to-finish: The footer shows an estimated reading time based on 250 words per minute. Hover for chapter-level and book-level estimates.

Reading progress

Progress is saved automatically as you read. The library shows a percentage on each book card. When you reopen a book, you return to exactly where you stopped. Folio also records reading sessions (time spent, pages read) for the reading stats dashboard.

Returning to the library

Click the back arrow in the top-left corner or press Escape. Your progress is saved when you exit.

PDF and Comic Book Reading

PDF, CBZ, and CBR formats use a page-by-page viewer. Navigate with the Previous/Next buttons, arrow keys, or mouse wheel. The footer shows the current page number and total page count.

Go to page: Click the page label in the footer (e.g., “Page 5 / 45”). It turns into a number input — type the page you want and press Enter. Press Escape or click away to cancel.

Zoom: Use Cmd/Ctrl + scroll to zoom in and out. A zoom level indicator appears with a reset button. Use Cmd/Ctrl + / − / 0 for keyboard zoom control. Zoom resets on page change.

When you zoom into a PDF, Folio re-renders the page at the higher resolution so text stays sharp — similar to how native PDF viewers work.

Highlights and Bookmarks

Highlights (EPUB only)

Select text while reading to see a color picker popup. Choose from five colors: yellow, green, blue, pink, or orange. The highlighted text is saved with its position.

Open the highlights panel to:

• View all highlights grouped by chapter
• Add or edit notes on any highlight
• Click a highlight to jump to that chapter
• Delete individual highlights
• Export all highlights as Markdown

Bookmarks

Press B in the reader to bookmark the current position. A toast notification appears — expand it to give the bookmark a name. You can also rename bookmarks later by clicking the name in the bookmarks panel (click to edit, Enter to save, Escape to cancel). Bookmarks are listed alongside your reading progress.

Full-Text Search (EPUB)

Search the full text of any EPUB book:

• Click the magnifying glass icon in the reader header or press ⌘/Ctrl+F to open the search bar.
• Type at least 2 characters to see results. Matches appear with chapter name and a text snippet.
• Click a result to jump to that chapter. Search highlights appear in blue in the text.
• Results are capped at 200 matches. If you hit the cap, try a more specific query.
• Press Escape to close the search panel.

Book Metadata Editing

Click the edit button on any book card to open the metadata editor.

Editable fields

• Title
• Author
• Series and volume number
• Language
• Publisher and publish year
• Cover image (upload a JPG, PNG, or WebP)
• Star rating (1–5 stars — click a star to rate, click the same star again to clear)
• Tags (with autocomplete from your existing tags)

Automatic Metadata Enrichment

Folio can automatically look up metadata for your books from multiple sources. Click “Search” in the edit dialog to manually look up a book by title and author, or let the auto-scan handle it.

Enrichment providers

Providers are tried in order — the first one that finds a match wins. Configure which providers are active in Settings > Metadata Scan > Enrichment Sources.

The scan uses multiple strategies in order of confidence:

1. ISBN lookup — if the book contains an ISBN in its metadata, Folio does a direct lookup (highest accuracy).
2. Title + Author search — searches providers and auto-applies if the match is strong.
3. Filename parsing — for CBR/CBZ comics and files with no embedded metadata, Folio parses the filename to extract title, author, and year.

Scan controls

• Scan Library button in the toolbar (magnifying glass icon) — scans all unenriched books. Also retries previously skipped books (they may match with newly enabled providers).
• Per-book scan — click the scan icon in the book detail popup to enrich a single book.
• Progress indicator — shows “Enriching 3/12: Book Title” with a cancel button.

Settings

• Auto-scan on import (default: on) — newly imported books are automatically queued for metadata lookup.
• Auto-scan on startup (default: off) — scan unenriched books when the app launches.

Comics metadata

Comics (CBZ and CBR) get metadata from two sources:

• ComicInfo.xml — if present inside the archive, Folio extracts writer, title, series, volume, year, language, publisher, genre, and summary automatically at import time.
• Enrichment providers — Comic Vine is recommended for comics. Get a free API key from comicvine.gamespot.com/api, enable it in Settings, then run a scan.

Catalog Browsing (OPDS)

Folio can browse online book catalogs that use the OPDS protocol (Open Publication Distribution System). This includes sources like Project Gutenberg, Standard Ebooks, and self-hosted Calibre servers.

Browsing

Open the catalog browser from the library. Pick a catalog to browse its categories and entries. Each entry shows the title, author, summary, and cover when available.

Searching

Unified search: From the catalog list, type a query in the “Search all catalogs” bar. Folio searches every configured catalog in parallel and shows aggregated results — one search, all sources.

Per-catalog search: When browsing inside a catalog that supports search, a “Search this catalog” bar appears at the top.

Downloading

Click a download link to grab a book (EPUB or PDF) and import it directly into your library.

Discover

The library home page includes a Discover section showing popular and new books from your configured OPDS catalogs. Results are cached for 24 hours and fetched in the background so they don’t slow down startup. Click any Discover card to download and import the book.

Custom catalogs

Add your own OPDS catalog by URL (useful for self-hosted Calibre or COPS servers). Custom catalogs can be removed at any time.

Themes

Click the gear icon in the reader header (or library toolbar) to open Settings. Choose from four presets or create your own:

• Light — warm off-white with brown text (default).
• Sepia — deeper amber/parchment background with rich brown text, designed for comfortable extended reading.
• Dark — dark background with light text for low-light environments.
• Auto — follows your operating system’s light/dark setting.

Custom colors: Click “Custom colors” to open the color editor. Pick a background and text color — the remaining UI colors are automatically derived. Expand “Advanced” to fine-tune individual color tokens.

Reading font

Choose from four built-in fonts for EPUB reading content:

• Lora — elegant serif font (default).
• Literata — a serif font designed for e-reading (created by Google for Play Books).
• DM Sans — clean sans-serif font.
• OpenDyslexic — a font designed for readers with dyslexia, with weighted letterforms that prevent visual rotation and flipping.

You can also add your own fonts: click Add font... at the bottom of the font list and select a .ttf, .otf, or .woff2 file. Custom fonts appear alongside the built-in options. To remove a custom font, hover over it and click the X icon.

Built-in fonts are bundled locally — no internet connection required.

Dual-Page Spread

Show two pages side by side, like an open book. Works for all formats: comics (CBZ/CBR), PDFs, and EPUBs in paginated mode.

Toggling on/off

• Reader header: Click the dual-page icon (two rectangles) in the header bar. When active, the icon highlights.
• Settings > Page Layout: Toggle “Dual-page spread” on or off.

Page pairing

The cover page (page 1) always displays solo. Subsequent pages are paired: 2–3, 4–5, 6–7, etc. If the last page has no partner, it displays solo.

Manga mode (right-to-left)

When dual-page is active, a second button appears in the header bar (left arrow icon). Toggle it to swap the page order within each spread — the right page displays on the left and vice versa. This also reverses the arrow key direction so that left-arrow advances forward, matching the RTL reading direction. For EPUBs, manga mode flows the text columns right-to-left.

Zoom and pan

In dual-page mode, zoom and pan apply to both pages as a unit. Pan is bounded so you can’t drag the content off-screen.

Both settings are global (apply to all books) and persist between sessions. Dual-page is automatically hidden when EPUB is in continuous scroll mode.

Font size

Adjust between 14px and 24px using the slider or +/− buttons in Settings, or the A−/A+ buttons in the reader header.

Page Turn Animation

When you turn pages in PDF or comic formats (CBZ/CBR), the new page slides in from the side with a short fade. It gives you a sense of direction when flipping forward or backward.

Toggle: Settings > Page Layout > “Page turn animation” — on by default. Turn it off if you prefer instant page changes.

Adjacent pages are preloaded in the background after you pause on a page, so the animation plays without any stutter. During fast navigation the preloads back off to keep the current page responsive.

This setting does not affect EPUB, which uses its own chapter-based navigation.

Advanced Typography

Fine-tune your reading experience under Settings > Text & Typography:

• Line height — adjust spacing between lines (1.2× to 2.4×).
• Page margins — control horizontal padding (0px to 80px).
• Text alignment — choose between left-aligned or justified text.
• Paragraph spacing — set the gap between paragraphs (0em to 2em).
• Hyphenation — toggle automatic word breaking at line endings.

All typography settings apply to EPUB content only and are saved globally.

Custom CSS

For advanced customization, you can inject your own CSS that applies to EPUB reading content:

1. Open Settings > Appearance and scroll to the Custom CSS section.
2. Type or paste CSS rules in the text area.
3. Changes apply immediately with a live preview.
4. Use the Clear button to remove all custom CSS.

Profiles

Profiles give you completely separate libraries. Each profile has its own books, reading progress, collections, and highlights.

Create and switch profiles from the profile dropdown in the library header. The dropdown only appears once you have more than one profile. Non-default profiles can be deleted.

Backup and Restore

From Settings > Backup & Restore you can export and restore library backups.

Export options

• Metadata only — small file containing your reading progress, collections, tags, and highlights.
• Full backup — includes all book files alongside the metadata.

Restore from backup

Click “Restore from backup” to open the restore picker:

• Automatic backups — Folio creates automatic backups before destructive operations like library cleanup. These are listed with their date, type, and file size. Click “Restore” on any entry.
• From file — Click “Choose file” to select a backup ZIP you exported previously.

Restoring a backup imports books and metadata. Existing data is not deleted — it’s a non-destructive merge.

Library cleanup

From Settings > Library, click “Check for missing files” to scan your library for books whose files no longer exist on disk (moved, deleted, or on a disconnected drive). Folio automatically creates a metadata backup before removing any broken entries. The result shows how many books were removed and where the backup was saved.

If you try to open a book whose file is missing, Folio shows a dialog offering to remove it from your library.

Remote backup

Folio can sync your library to a remote storage provider. Configure in Settings > Remote Backup.

How it works: Select a provider, fill in connection details, and click Save Configuration. Passwords are stored in your OS keychain, not in the database. Click Backup Now to start a sync.

Book files are uploaded incrementally — only new or changed files are transferred. Metadata files always contain the full library. During backup, the button shows real-time progress like “Uploading books 3/12”. If a backup is interrupted, the next run picks up where it left off. Both successful and failed backups are logged in the activity log.

Multi-device Sync

If you read on more than one computer, Folio can keep your reading progress, bookmarks, and highlights in sync across devices. Sync piggybacks on the same remote storage provider you already configured for backup.

Enabling sync

1. Configure a remote backup destination (S3, FTP, SFTP, or WebDAV) as described above.
2. In Settings > Remote Backup, toggle “Sync reading progress across devices” on.

How it works

• When you open a book: Folio checks the remote storage for newer data from other devices. If another machine has more recent progress, bookmarks, or highlights, they are merged into your local library. This happens in the background with a 5-second timeout — the book opens immediately regardless.
• When you close a book: Folio pushes your current reading state to remote storage in the background. Other devices pick up those changes next time they open the same book.
• Book matching: Books are matched by content hash (SHA-256), so the same file on different devices syncs correctly even if the filenames differ.

What syncs

• Reading position (chapter and scroll position)
• Bookmarks (including names and notes)
• Highlights (including colors and notes)
• Deletions — removing a bookmark or highlight on one device removes it on others

What does not sync

• Book files (use backup for that)
• Collections, tags, or star ratings
• Reading statistics
• Settings or theme preferences

Conflict resolution

When the same item is edited on two devices, the most recent edit wins (based on timestamps). If timestamps are equal, the remote version is preferred. This is automatic — no manual conflict resolution needed.

Sync status

When sync is on, the Settings panel shows the time of the last successful sync. If a sync fails (network issues, server unreachable), an error message appears and clears automatically after the next successful sync.

Sync and backup are independent features. Sync is a lightweight, per-book data exchange for reading state. Backup is a full library export. You can use one without the other, though both need a remote storage provider.

Remote Access

You can browse and read your library from any device on the same WiFi network — a phone, tablet, or another computer — without installing anything. Folio runs a small web server on your machine and serves the library over your local network.

Setting up

1. Open Settings and scroll to the Remote Access section.
2. Enter a PIN (this is the password for web access) and click Save PIN.
3. Click Start Server.
4. A URL and QR code appear. Scan the QR code with your phone or type the URL into any browser.

The server runs on port 7788 by default. You can change the port before starting.

Using the web interface

On your phone or tablet, open the URL in a browser. You get:

• Login screen — enter the PIN you set in the desktop app.
• Library — a grid of book covers with a search bar. Tap any book for details.
• Book detail — shows cover, title, author, and format. Tap Read to open the book or Download to save it to your device.
• Reader — EPUBs show chapter content with prev/next navigation. PDFs and comics show page images with prev/next buttons.

Everything stays on your local network. No internet connection needed, no data leaves your WiFi.

OPDS for reader apps

If you use a reader app that supports OPDS (KOReader, Calibre, Moon+ Reader, etc.), you can connect it directly to Folio:

1. In the reader app, add a new OPDS catalog.
2. Enter the URL: http://<your-ip>:7788/opds
3. For authentication, use HTTP Basic Auth with any username and your PIN as the password.
4. Browse your library and download books into the reader app.

Auto-start

If the server was running when you last closed Folio, it starts automatically next time you open the app. Stop the server from Settings to disable auto-start.

Security

• Your PIN is hashed (SHA-256) and stored in your OS keychain.
• Web sessions expire after 24 hours.
• Login attempts are rate-limited (5 tries per 5 minutes per device).
• The server is read-only — nobody can modify your library from the web interface.
• All served content is sanitized to prevent malicious scripts in EPUB files.

Stopping the server

Click Stop Server in Settings. The server also stops when you close the Folio app.

Activity Log

Folio keeps a log of data-changing actions (imports, edits, deletes, collection changes, backup/restore, profile switches, and more):

• Open Settings > View Activity Log to browse recent activity.
• Filter by action type (e.g., only imports, only edits).
• Each entry shows the action, affected item, and timestamp.
• Pagination via “Load more” for long histories.

Reading Stats

Open the reading stats dashboard from the library toolbar (bar chart icon).

Tracked metrics

• Time Reading — total time spent in the reader.
• Sessions — number of reading sessions.
• Pages Read — total pages turned (PDF/CBZ/CBR).
• Books Finished — books read to completion.
• Current Streak — consecutive days with reading activity.
• Longest Streak — your all-time record.

A 30-day bar chart shows your daily reading time over the past month. Stats are tracked automatically — reading sessions are recorded when you open and close a book.

Language

Folio supports multiple interface languages. Currently available: English and French.

• Switching: Click the flag icon in the library toolbar or reader header. A dropdown shows available languages with flag emojis. Select one to switch immediately — no restart needed.
• Auto-detection: On first launch, Folio detects your operating system language. If it matches a supported language, that language is used. Otherwise, English is the default.
• Persistence: Your language choice is saved and remembered across sessions.

Keyboard Shortcuts

Press ? at any time to see the shortcut reference.

Library

Reader

Troubleshooting

“Failed to load book”

The file is probably corrupted or uses a format variant the parser can’t handle. Try re-downloading the file, or open it in another reader to check if the file itself is the problem.

Supported formats

Folio supports EPUB (versions 2 and 3), PDF, CBZ, and CBR. Other formats such as MOBI, AZW, and DjVu are not supported.

Where is my data stored?

Library database and app data:

Book files: Imported books are copied to the library folder, which defaults to ~/Documents/folio/. You can change this in Settings. Since Folio keeps its own copy of each book, moving or deleting the original file has no effect on your library.

The app won’t start

Check that your OS meets the minimum version listed in Getting Started.

macOS — “damaged and can’t be opened”: This is a Gatekeeper quarantine flag on unsigned apps. Run the following in Terminal, then try launching again:

xattr -cr /Applications/Folio.app

Alternatively go to System Settings > Privacy & Security and click Open Anyway after the first blocked launch attempt.