Miro is a native PDF viewer designed to provide a seamless experience across Windows, macOS, and Linux (Wayland/X11) platforms. It offers configurable keybindings and a range of features tailored for efficient document navigation and customization.
Key Features:
Dark Mode: Enjoy both dark interface and PDF rendering modes.
Vim-Like Keybindings: Use customizable keyboard shortcuts for streamlined navigation.
Multiple Tabs: Open and manage several PDFs simultaneously.
Text Copying and Search: Extract text and perform full-text searches, including regex.
Bookmarks and Annotations: Save bookmarks and view annotations within documents.
Command-Line Integration: Open PDFs directly from the terminal.
Target Audience and Benefits:
Ideal for power users, developers, and professionals who prioritize customization and efficiency. Miro enables users to tailor their experience with configurable keybindings and settings, making it perfect for workflows that demand precision and speed.
Available via Winget, you can install or deploy Miro using the winget command line, ensuring smooth integration into your system.
README
miro
A native pdf viewer for Windows, macOS and Linux (Wayland/X11) with configurable keybindings.
Features
Dark mode (both for the interface and the pdf)
Vim-like keybindings (by default)
Configuration file for key bindings (in case you don't like Vim bindings)
Mouse controls
Multiple pdfs in tabs
Cli arg for opening pdfs from the terminal
Automatic hot-reloading of any viewed pdf (especially useful when writing anything that compiles into pdfs like Latex/Typst/etc.)
Text copying in documents
Internal links (such as a table of contents)
External links (email, websites, etc. copies on click)
Bookmarks
Jumplist
Optional RPC server to control the viewer from another program
Print via the default web browser
Open links using keyboard controls
Fullscreen
A presentation mode that hides all UI
Shows recently opened files
Search through documents using plain text or regular expressions
Read comments and show annotations
Configuration
The configuration file is located at ~/.config/miro-pdf/miro.conf (or .config/miro-pdf/miro.conf in the home directory of your operating system). An example configuration file is located at /assets/default.conf which contains all the default bindings for the program.
Every binding that is possible is bound at least once in the default configuration file.
Configuration File Format
The configuration file uses a simple text format with three types of commands and comments:
Key Bindings
Bind
Key sequences can be:
Single keys: j, k, h, l
Modified keys: Ctrl+r, Shift+Tab
Key chords (multiple keys): "Z Z" (quotes required for sequences with spaces)
All available actions are bound in the example config file. If you need a more exact view of the syntax it is documented in the keybinds-rs crate.
All available actions are bound in the example config file.
Settings
Set
Available settings:
Rpc - Enable/disable RPC server
RpcPort - Set RPC server port
TrackpadSensitivity - Set a multiplier on panning with a trackpad
Default Settings
Set
Default settings apply only at application startup. They can later be toggled with key bindings.
Available default settings:
DarkModePdf - Enable/disable dark mode rendering of the PDF
DarkModeUi - Enable/disable dark mode for the UI
OpenSidebar - Open sidebar
PageBorders - Enable/disable page borders
Comments and Empty Lines
# This is a comment
# Comments start with # and are ignored during parsing
# Empty lines are also ignored
Error Handling
The configuration parser provides detailed error messages with line numbers when parsing fails. Errors on one line don't prevent parsing of other lines
Example error output:
Configuration parsing errors:
Line 3: Unknown command: InvalidCommand
Line 5: Unknown action: InvalidAction
Line 7: Invalid port number: 'not_a_number'. Must be a valid integer
Installation
Pre-compiled binary
Head over to releases and download the latest binary for your platform, then place it somewhere in your path.
This is pretty much the same as the following option, but doesn't require cloning the repo. See building from source for possible complications when compiling for Windows. I've had no problems compiling on Linux thus far.
cargo install miro-pdf
Building from source
On linux, the commands below would clone the repository, compile the project and copy the resulting binary to /usr/bin/.
git clone https://github.com/vincent-uden/miro.git
cd miro
cargo r --release
cp ./target/release/miro-pdf /usr/bin/miro-pdf
Windows
On Windows, the same rough process should work, but often doesn't. I highly recommend downloading a precompiled binary for Windows. The problem lies in compiling the crate mupdf-sys which requires MSVC.
The Visual Studio project embedded in this crate requires Visual Studio 2019 which isn't available for downloading anymore, but can optionally be compiled using Visual Studio 2022. Even with this option, the build might just not work sometimes due to issues with the Windows 10/11 SDK kits which I have not managed to solve.
However, I've managed to get compilation working in github actions which is what produces the release binaries which do function correctly on Windows systems.
Linux
Mupdf-rs requries headers for fontconfig. The packages are:
libfontconfig1-dev on Ubuntu/Debian
fontconfig-devel on Fedora
fontconfig on Arch and derivatives
Building on linux also requires some hidden dependencies that you probably already have.
clang
unzip
macOS
While I don't test the software for macOS since I don't own a mac. It should work although only supporting building from source or crates.io. No binary releases are made.
