Sioyek

1 General information

Website: https://sioyek.info/
Repository: https://github.com/ahrm/sioyek
Documentation: https://sioyek-documentation.readthedocs.io/
Supported formats: pdf, epub.
Uses Vim style for keyboard shortcuts.

2 Installation

yay -S sioyek

3 Configuration

Configuration file

Keyboard system settings: /etc/sioyek/keys.config.
System general settings: /etc/sioyek/prefs.config.

Install as default application

The default application is installed using xdg-utils (see XDG MIME Applications ):

xdg-mime default sioyek.desktop application/pdf

4 Default key bindings

Opening files

o: open file selection menu ( open_document);
Shift-o: open list of recently opened files ( open_prev_doc);
Ctrl-o: open built-in file system browser ( open_document_embedded);
Ctrl-Shift-o: open the built-in file system browser in the current document folder ( open_document_embedded_from_current_path);
delete: remove a file from the list (does not delete a file in the file system);
Ctrl-t: open the file in a new window;
The command line option --new-window: opens a new window from the inside;
The command goto_window: allows you to switch between open windows.

Settings

I find it more convenient to open a new window for each file:

## If set, we open a new sioyek window when a new file is opened, otherwise we open the file in the previous window
should_launch_new_window 1

Moving

Press HOME, a menu will open in which you can enter the page number: go to the desired page ( goto_page_with_page_number);
space: move one screen down;
Shift-space: move one screen up;
Ctrl-PageDown, Ctrl-PageUp: go to next or previous page ( next_page, previous_page);
t: open searchable table of contents ( goto_toc);
gc: go to next chapter ( next_chapter);
gC: go to previous chapter ( prev_chapter);
The command toggle_scrollbar toggles the scrollbar.

Scaling

System settings

f9 / =: fit page to window width ( fit_to_page_width);
f10: Fit the page to the width of the window, ignoring page margins ( fit_to_page_width_smart).

Settings

a: adjust to page height:

## Similar to fit_to_page_width, but for height
fit_to_page_height  a

Shift-a: adjust to page height:

## Similar to fit_to_page_width_smart but for height
fit_to_page_height_smart  S-a

s: fit the page to the width of the window ( fit_to_page_width):

## Fill the screen width
fit_to_page_width  s

Visually I separate the pages:

## Configure the appearance of page separator
page_separator_width 2
page_separator_color 0.9 0.9 0.9

A complete location history is stored.
backspace or Ctrl-LeftArrow: go back through history;
Shift-backspace or Ctrl-RightArrow: go back forward in history.

Overview

You can right-click a link to open a quick overview of the link’s destination; You can navigate this overview using the mouse wheel;
If there are no links in the PDF document, you can right-click on the elements and the viewer will try to open an overview of the element’s destination;
Middle-click on items to go directly to their location instead of opening an overview.

Visual cue

If you right -click on a line of text in a PDF file, sioyek will display a visual highlight below that line (visual label).
You can always return to the last visual cue location by clicking and then right-clicking or clickingagain. an be used to track a string.
You can move the visual cue to the next or previous line by pressing j or k (move_visual_mark_down, move_visual_mark_up).
You can switch the visual scrolling mode by clicking F7 (toggle_visual_scroll). In this mode, the mouse wheel moves the visual cue up and down.
If set to prefs_user.config command ruler_mode 0, the line is simply underlined.
If set to prefs_user.config command ruler_mode 1, draws a rectangle around the current line.
While a row is highlighted, you can click l (overview_definition) to create a link overview on the current row.

Similarly, you can click ] (portal_to_definition) and Ctrl+] (goto_definition) to create a portal or go to a definition.

Search

/ or Ctrl-f: open the search menu ( search);
c/: search only in the current chapter ( chapter_search);
Commands overview_next_item and overview_prev_item can open an overview of search results rather than jump to them.

Settings

Let’s enable quick search:

## Use a super fast index for search instead of the mupdf's implementation
super_fast_search 1

When searching, we will not take into account the case of characters:

## Use case-insensitive search
case_sensitive_search 0

Bookmarks

Bookmarks are similar to tags, except that they use a text description instead of a letter of the alphabet.
You can add a bookmark by pressing b (add_bookmark) and then entering a text description of the bookmark in the menu that opens.
You can open a searchable list of the current document’s bookmarks by typing gb (goto_bookmark).
You can open a searchable list of all bookmarks in all documents by typing gB (goto_bookmark_g).
You can delete the bookmark closest to your current location by entering the command db (delete_bookmark).
You can also remove bookmarks directly from the bookmark list by selecting the bookmark and then pressing a key delete on your keyboard.

Allocations

You can highlight text. Similar to labels, you can assign a type to each selection using a lowercase letter of the alphabet. Each type is assigned its own color.
Select a piece of text, then press , h followed by a letter to set the type. For example, to create a selection of type a, enter ha (add_highlight).
If you don’t want to specify the selection type each time, you can run the command add_highlight_with_current_type, which uses the current selection name for the selected text.
You can change the current selection type by running the command set_select_highlight_type.
You can switch the selection mode by running the command toggle_select_highlight. In this mode, all selected text will be highlighted as the selected selection type.
Click gh to open a searchable list of selections in the current document (goto_highlight).
Click gH to open a searchable list of highlights in all documents (goto_highlight_g).
You can execute goto_next_highlight and goto_prev_highlight to move through the highlighted points in the current document.
If you want to navigate through the selected objects of the selected type (name), you can use the goto_next_highlight_of_type and commands goto_prev_highlight_of_type.
To delete a selection, first left-click it and then type dh (delete_highlight).
You can also press a key delete on your keyboard in the selection list.

Portals

Sometimes a paragraph is entirely devoted to the previous part of the document. For example, perhaps this paragraph explains the data in the previous table, describes the previous figure, or answers the previous exercise.
In such situations, it is usually very annoying to constantly switch between a paragraph and the material being referenced.
Using portals, you can link the location of a paragraph to the location of the referenced material, and whenever you scroll to a paragraph, the content of the link is automatically displayed in a secondary window.
To create a portal, click p (portal). This creates an incomplete portal with the current location as the source.
Now navigate to the location of the specified material and click p again. This concludes the portal with the second destination.
You can also create portals by clicking p and then clicking the PDF link. This automatically creates a portal from the link location to the link destination.
You can also middle-click after pressing p, which uses Smart Jump to determine your destination.
To view the portal, you need to open the assistant window. You can open or close the assistant window by clicking F12 (toggle_window_configuration).
This window automatically displays the portal destination with the closest source to your current location.
You can delete a nearby portal by entering dp (delete_portal).
You can navigate to the destination of the nearest link by running the command goto_portal.
To edit the destination of the current link, click Shift-p (edit_portalbackspace). This will automatically redirect you to the link’s destination. You can now adjust the screen or zoom level. When you’re done, return to the original location, returning to the story.
You can also edit the link destination by directly moving the assistant window with the mouse or scrolling the mouse wheel.
You can also adjust the zoom level by using the mouse wheel while holding down the button ctrl.

Command mode

System settings

Opened using :.

This is a searchable list of all commands, along with their current keyboard shortcuts.

Settings

M-x: bring up the command menu:

## Open command line
command  <A-x>

External search

Select a piece of text and type ss or sl (the commandexternal_search followed by a letter a-z) to search Google Scholar or Library Genesis .
You can also middle-click or middle-click on the titles of articles or books (no need to highlight the text) to quickly find them in Google Scholar or other search engines.
You can configure search engines using configurationssearch_url_* in prefs_user.config.
You can configure which search engines to use for middle-click or shift-middle-click searches using themiddle_click_search_engine and configurations shift_middle_click_search_engine in prefs_user.config.
The value of these configurations must be the letter corresponding to the configurationssearch_url_*.

SyncTeX

Click F4 to switch sync mode (toggle_synctex).
In this mode, right-clicking on any text opens the corresponding tex file in the corresponding location.
You can configure the synctex reverse lookup command using the configuration inverse_search_command in prefs.config.

Data and synchronization

The data is stored in two database files named local.db and shared.db.
local.db stores system-specific data (such as the location of PDF files on your file system).
shared.db stores all other data, including tags, bookmarks, portals, etc.
shared.db can be used on different computers.
The path to the shared database is specified in the configuration shared_database_path in the prefs_user.config.
You can export and import data from a json file by running the command export or import.

Settings

Let’s place the shared database in a folder that is synchronized between devices (see Synchronizing files using syncthing ):

## Path to shared.db database file. If not set, we use the default path.
## you can set this to be a file in a synced folder (e.g. dropbox folder) to automatically sync
## sioyek across multiple computers
shared_database_path    ~/Sync/local/sioyek/shared.db

Window configuration

Switch full screen mode using F12 (toggle_window_configuration). You can save the current window configuration with the command copy_window_size_config.

Miscellaneous

You can open links in PDF files using your keyboard by clicking f and entering the number next to the link you want (open_link).
Tap F8 to switch to dark mode.
Click F5 to switch to presentation mode.
The command toggle_horizontal_scroll_lock prohibits horizontal scrolling of the document.
The command toggle_custom_color switches the custom color scheme.
The command execute opens a command prompt where you can run shell commands.
You can export a version of the current PDF with all the bookmarks/highlights built into it (so it is available to other PDF software) by running the command embed_annotations.
You can rotate the page by running the commands rotate_clockwise and rotate_counterclockwise.

Configuration files

System-wide key binding file

File /etc/sioyek/keys.config:

# you can edit this file to change keybindings lines that start with '#' are comments
# the syntax is pretty simple. Some examples:
#command        k             (command is executed when k is pressed)
#command        <C-k>         (command is executed when k is pressed while holding control)
#command        K             (command is executed when K is entered, which is shift+k)
#command        <A-k>         (command is executed when k is pressed while holding alt)
#command        +             (command is executed when = is pressed while holding shift)
#command        <C-S-k>       (command is executed when k is pressed while holding control and shift)
#command        gg            (command is executed when g is pressed twice)
#command        gt            (command is executed when g is pressed and then t is pressed)
#command        g<C-n>Dt  (command is executed when g is pressed and then n is pressed while holding\
#                               control and then d is pressed while holding shift and then t is pressed)
# you can execute multiple commands using the following syntax:
#command1;command2;command3        <keybinding>
# for more information see the documentation at https://sioyek-documentation.readthedocs.io/


# ---------- NAVIGATION AND ZOOM ----------

# Goto the beginning of document. If prefixed with a number, it will go to that page.
# for example 150gg goes to page 150.
goto_beginning gg
goto_beginning <C-<home>>

# Goto the end of the document
goto_end <end>
goto_end G

# Opens a prompt to enter page number and jump to that page
goto_page_with_page_number <home>

## Goto left/right/bottom/top side of the page
#goto_left <unbound>
#goto_right <unbound>
#goto_top_of_page <unbound>
#goto_bottom_of_page <unbound>

# Goto left/right side of the page ignoring white margins
goto_left_smart ^
goto_right_smart $

# Goto the top-right side of page. Useful for two column documents
goto_top_of_page;goto_right_smart zz

# Movement (can be prefixed with a number)
# move_down           <down>
# move_up             <up>
move_left           <right>
move_right          <left>

# Goto forward for one page width. (can be prefixed with a number)
# (note that going forward for one page width is not usually what you want because if
# the page is larger than the screen you will miss some content. What you usually want is screen_down)
next_page <C-<pagedown>>
previous_page <C-<pageup>>

# Go down one screen width (can be prefixed with a number which tells how many screen widths should we go down)
screen_down <space>
screen_up <S-<space>>
screen_down <pagedown>
screen_up <pageup>

# Goto the next/prev chapter
next_chapter gc
prev_chapter gC

# Goto previous viewing state and delete the current (and future) state(s).
# pop_state w

# Goto the previous history point
prev_state <backspace>
prev_state <C-<left>>

# Create a new sioyek window
new_window <C-t>

# Close the current sioyek window
close_window <C-w>

## Search and switch between sioyek windows
#goto_window <unbound>

# If we are not at the end of viewing history, goto the next history point
next_state <S-<backspace>>
next_state <C-<right>>

# Open table of contents.
goto_toc t

# Zoom
zoom_in  +
fit_to_page_width =
zoom_out -

## Zoom in/out on the mouse cursor (instead of center of screen)
# zoom_in_cursor <unbound>
# zoom_out_cursor <unbound>

# Rotate document
rotate_clockwise r
rotate_counterclockwise R

# Automatically set the zoom level and horizontal offset such that the current page is centered horizontally and
# it fills the screen width
fit_to_page_width <f9>
# Same as fit_to_page_with but ignores page margins
fit_to_page_width_smart <f10>

## Similar to fit_to_page_width, but for height
#fit_to_page_height   <unbound>

## Similar to fit_to_page_width_smart but for height
#fit_to_page_height_smart   <unbound>

## Same as fit_to_page_width, but instead of filling the screen width, it fills the ratio of screen that is
## configured in `prefs_user.config` using `fit_to_page_width_ratio` config. See https://github.com/ahrm/sioyek/issues/162#issuecomment-1059738730.
#fit_to_page_width_ratio <unbound>

# Open a file dialog to select a document.
open_document o
# Open an embedded file dialog in sioyek
open_document_embedded <C-o>
# Open an embedded file dialog in sioyek rooted in the directory of current opened file
open_document_embedded_from_current_path <C-S-o>

# Open a searchable list of previously opened documents.
open_prev_doc O

## Opens the last document opened is sioyek. It is useful when you want to quickly toggle between two documents
#open_last_document <unbound>

## Keyboard shortcut to enter visual mark mode (instead of right clicking)
#enter_visual_mark_mode <unbound>

# Command the move the visual mark to the next/previous line
# these keys only work when a visual mark is set (by right clicking or using `visual_mark_under_cursor` command)
move_visual_mark_up k
move_visual_mark_down j
move_visual_mark_up <up>
move_visual_mark_down <down>

## lock horizontal scroll, useful when using laptop touchpads
# toggle_horizontal_scroll_lock <unbound>

# ---------- SEARCH ----------

# Search the document.
# example: /something                   (searches the document for 'something')
# you can also specify a page range to search:
# example: /<110,135>something          (searches pages 110 to 135 (inclusive) for 'something')
search <C-f>
search /

# Searches the current chapter. This is essentially the same as search but the range prefix is autofilled
# with the range of the current lowest level subchapter.
chapter_search c<C-f>
chapter_search c/

# Goto the next search item. Can be prefixed with a number which is the same as performing the command n times
# for example if we are on the 10th search result and we input 15n, we go to the 25th search result.
next_item n
# Goto the previous search result. Can be prefixed with a number with similar rules as next_item.
previous_item N

# ---------- BOOKMARKS ----------
# Add a bookmark in the current location (opens a text input where you can specify the bookmark text)
add_bookmark b
delete_bookmark db

# Open bookmarks menu of the current document.
goto_bookmark gb

# Open bookmarks menu of all documents.
goto_bookmark_g gB

# ---------- HIGHLIGHTS ----------
# You can select a piece of text and press the `add_highlight` shortcut followed by a symbol (a character from a-z) to highlight
# the text
add_highlight h
# Goto highlights of current document
goto_highlight gh
# Goto highlights of all documents
goto_highlight_g gH
# Left click on a highlight and then press the `delete_highlight` shortcut to delete it.
delete_highlight dh

# Sets the highlight type to be used for other operations (the default highlight type is 'a')
#set_select_highlight_type

## Same as `add_highlight` but uses the current selected highlight type as the type of highlight
#add_highlight_with_current_type <unbound>

## Toggle select highlight mode. In select highlight mode, all text selected using mouse will automatically be highlighted
## with highlight type set using `set_select_highlight_type`
#toggle_select_highlight <unbound>

# Goto next/previous highlight in current document
goto_next_highlight gnh
goto_prev_highlight gNh

## Goto next/previous highlight of the current selected highlight type
#goto_next_highlight_of_type <unbound>
#goto_prev_highlight_of_type <unbound>

# ---------- MARKS ----------

# Mark the current location. After pressing the mark button, you must enter a symbol (a letter from a-z or A-Z).
# this marks the current location in the file with the entered symbol. Afterwards you will be able to return to
# the locations of the marks using goto_mark command.
# example:  mm      (marks the current location in the file with a mark named 'm')
set_mark m
# Goto a previously set mark. After pressing goto_mark you must enter a symbol associated with a previously set mark.
# example:  `m      (goes to the location of the mark named m)
goto_mark `

# ---------- PORTALS ----------
# If we are in default state, goto portal state with the current location in document as the portal source
# if we are already in the portal state, create the portal with the current location as destination.
portal p

# Delete the portal with the closest source to current location
delete_portal dp

# Goto the position of the portal with the closest source to current location
goto_portal gp
goto_portal <tab>

# Similar to goto_portal, except when prev_state is called, the destination of the portal is update to be the state
# on which prev_state is called
edit_portal P
edit_portal <S-<tab>>

# Open/Close the helper window for portals
toggle_window_configuration <f12>

## open/close helper window
#toggle_one_window <unbound>

# ---------- MISC ----------

# Copy selected text
copy <C-c>

toggle_fullscreen <f11>

# Toggles whether we highlight pdf links or not
toggle_highlight <f1>

# open command line
command :

# Search the selected text using one of the search engines defined using search_url_* settings in prefs.config (* can be any letter between 'a' and 'z')
# see https://sioyek-documentation.readthedocs.io/en/latest/usage.html#external-search
external_search s

# opens the selected text as a url in the default browser
# open_selected_url Q

# Toggle dark mode (inverted colors)
toggle_dark_mode <f8>

## Toggle custom color mode. You can specify the text background color in your `prefs_user.config` file
## see https://sioyek-documentation.readthedocs.io/en/latest/configuration.html#custom-background-color-and-custom-text-color
#toggle_custom_color <f8>

# Toggle synctex mode. When in synctex mode, right clicking on a pdf launches the corresponding latex page.
toggle_synctex <f4>

## Perform a synctex search under the mouse cursor
#synctex_under_cursor <unbound>

# While in mouse drag mode, instead of selecting text you can pan the screen using mouse
toggle_mouse_drag_mode <f6>

# In visual scroll mode, mouse wheel performs `move_visual_mark_up` and `move_visual_mark_down` commands
toggle_visual_scroll <f7>

# In visual scroll mode, create an overview to/go to/portal to the definition in highlighted line
overview_definition l
goto_definition <C-]>
portal_to_definition ]

# In presentation mode, we fit the pages to screen and movement keys move entire pages
toggle_presentation_mode <f5>

## Quit sioyek
quit q

# Open PDF links using keyboard
open_link f

# Select text using keyboard
keyboard_select v

# Smart jump using keyboard
keyboard_smart_jump F

## Open overview window using keyboard
#keyboard_overview <unbound>

## If the preview is not correct, jump to the next preview
#next_preview <C-n>

## If the preview is not correct, jump to the previous preview
#previous_preview <C-N>

## Jump to the location of the current overview
#goto_overview <unbound>

## Create a portal to the location of the current overview
#portal_to_overview <unbound>

## Center the window on selected text
#goto_selected_text <unbound>

## Focus the visual mark on the text matching the given string (useful when extensions want to focus on a text)
#focus_text <unbound>

## Smart jump to the location under mouse cursor
#smart_jump_under_cursor <unbound>
## Open overview window to the location under mouse cursor
#overview_under_cursor <unbound>
## Set a visual mark under mouse cursor
#visual_mark_under_cursor <unbound>
## Close the overview window
#close_overview <unbound>
## Exit visual mark mode
#close_visual_mark <unbound>

## Import sioyek data from an exported file
#import <unbound>

## Export sioyek data into a json file
#export <unbound>

## Execute shell commands. For example:
## sioyek --new-instance %1
## in the command %1 expands to the path of the current file and %2 expand to the file name of the current file
#execute <unbound>

## (deprecated see bottom of the page) Execute a predefined command. these commands are defined in `prefs_user.config` file using the following syntax:
## --------prefs_user.config-----------
## execute_command_a some_command %1 %2
## execute_command_x another_command %2
## ------------------------------------
## now in order to execute the second command you can first execute `execute_predefined_command` and then press 'x'
#execute_predefined_command <unbound>

## Embed the annotations (highlights and bookmarks) into a new PDF file so they are visible to other PDF readers
#embed_annotations <unbound>

## Copy the current window configuration to clipboard so they can be used in `prefs_user.config`
#copy_window_size_config <unbound>

## Opens the default preference file
#prefs <unbound>
## Opens the user preference file with highest priority
#prefs_user <unbound>
## Opens a list of all user preference files
#prefs_user_all <unbound>

## Opens the default kwys file
#keys <unbound>
## Opens the user keys file with highest priority
#keys_user <unbound>
## Opens a list of all user keys files
#keys_user_all <unbound>

## Enter password for password protected documents
#enter_password <unbound>

## Toggle fastread mode. this is an experiental feature
#toggle_fastread <unbound>

## Toggle statusbar display
#toggle_statusbar <unbound>

## Reload sioyek window
#reload <unbound>

## Set the status string to be displayed in sioyek's statusbar (it is useful for extensions)
#set_status_string <unbound>

## Clears the status string set by `set_status_string`
#clear_status_string <unbound>

## Toggles the window titlebar
#toggle_titlebar <unbound>

## You can bind custom commands defined in `prefs_user.config` using the same syntax as the built-in commands
## --------prefs_user.config-----------
## new_command _my_command_name python /path/to/script.py %{file_name} %{paper_name}
## ------------------------------------
## now you can bind _my_command_name to a keybind here:
#_my_command_name <unbound>

Custom Key Binding File

File ~/.config/sioyek/keys_user.config.

System-wide preference file

File /etc/sioyek/prefs.config:

User preference file

File ~/.config/sioyek/prefs_user.config.

Sioyek

1 General information

2 Installation

3 Configuration

Configuration file

Install as default application

4 Default key bindings

Opening files

Settings

Moving

Scaling

System settings

Settings

History navigation

Overview

Visual cue

Search

Settings

Tags

Bookmarks

Allocations

Portals

Command mode

System settings

Settings

External search

SyncTeX

Data and synchronization

Settings

Window configuration

Miscellaneous

Configuration files

System-wide key binding file

Custom Key Binding File

System-wide preference file

User preference file