Usage

Note that all the keybindings in this section are the default keybindings that can be changed by editing keys_user.config. Each key executes a command. In order to add a keybinding that executes a command, you add the following to keys_user.config:

command key

For example suppose you want to use the j key to move down. You can add the following to your config file:

move_down j

Opening Files

  • Press o to open the select file menu. (open_document command)

  • Press <Shift o> (O) to open a searchable list of recently opened files. (open_prev_doc command)

  • Press <Ctrl o> to open an embedded file system browser. (open_document_embedded command)

Basic Movement

  • You can move the screen using the arrow keys. (corresponding to the following commands: move_down, move_up, move_left and move_right)

  • You can also use the mouse wheel to scroll the screen.

  • Press gg to go to the first page and G to go to the last page. (goto_begining and goto_end commands)

  • In order to go to a specific page you can enter the page number and then press gg. For example in order to go to page 42, you should enter 42gg.

  • To go to a specific page, you can also press the HOME button which opens a menu where you can enter the page number. (goto_page_with_page_number command)

  • You can prefix most commands with a number n which usually means repeat that command n times. For example pressing 10<down arrow> is equivalent to pressing down arrow 10 times.

  • Press space to move the screen down and <Shift space> to move the screen up. (screen_down and screen_up commands)

  • Press <Ctrl PageDown>/<Ctrl PageUp> to go to the next/previous page. (next_page and previous_page commands)

  • Press t to open a searchable table of contents. You can jump to table of content entries by selecting. (goto_toc)

  • Press gc to go to the next chapter and gC to go to the previous chapter. (next_chapter and prev_chapter commands)

Zoom

  • Press + (<Shift =>) to zoom in and - to zoom out. (zoom_in and zoom_out commands)

  • You can also use the mouse wheel while holding control to zoom in/out.

  • Press f9 to fit the page to window width. (fit_to_page_width command)

  • Press f10 to fit the page to window width ignoring white page margins. (fit_to_page_width_smart command)

History Navigation

Sioyek keeps a full, browser-like history of your locations. For example suppose you click on a link in the PDF file to go to a figure. You can now return back to the location of the link by issuing the prev_state command. Now, you can again return to the figure by issuing next_state command. Note that this history even works across multiple documents. For example if I am viewing document A.pdf and then open B.pdf I can return back to A.pdf by going back in history.

  • You can go back/forward in history by pressing backspace/<Shift backspace> or Ctrl LeftArrow/Ctrl RightArrow. (prev_state and next_state commands)

Overview and SmartJump

_images/overview.png
  • You can right click on PDF links to open a quick overview of the link destination. You can navigate in this overview using mouse wheel.

  • Even if the PDF document has no links, you can right click on items and sioyek tries to open an overview of item destination. For example right clicking on the text “Figure 2.19” opens an overview showing (hopefully) Figure 2.19 . This also works with equations, tables, references, etc.

  • You can also middle click on items to directly jump to their location instead of opening an overview.

Underline

_images/visual_mark.png

If you right click on a line of text in a PDF file, sioyek displays a visual highlight below that line (we refer to this as the “visual mark” from now on). This visual mark has multiple use-cases.

  1. It can act as a simple mark (see Marks). You can always return to the last location of visual mark by pressing ` and then right-clicking. This can be useful when you want to quickly check previous pages and jump back to where you were.

  2. It highlights the current line being read which reduces eye strain and prevents losing your place in PDF files.

  • You can move the visual mark to the next/previous line by pressing j/k (move_visual_mark_down and move_visual_mark_up commands).

  • You can toggle visual scroll mode by pressing f7. In this mode, mouse wheel moves the visual mark up and down.

Marks

Sometimes while reading a document, you need to glance at the contents of previous pages and quickly return to the original location. For example, maybe you forgot the definition of a term that was defined a few pages ago, or perhaps the current paragraph is referencing a previous figure. Using marks, you can mark your location before glancing at previous content and then quickly return to the location of the mark.

  • In order to create a mark, first press m (set_mark command) followed by an alphabet symbol (this symbol will be the name of the mark, you can have multiple marks with different names). For example, in order to create a mark named a for your current location, enter ma.

  • You can go to a mark by pressing ` followd by the name of the mark (note that ` is different from single quote '. ` usually is on the same key as ~). For example, in order to go back to the mark created in the previous example, enter `a. (goto_mark command)

  • Marks are persistent (they are saved even when sioyek is closed).

  • Lower case marks are local to the current document but upper case marks are global across sioyek.

Bookmarks

Bookmarks are similar to marks except they use a textual description instead of an alphabet letter.

  • You can add a bookmark by pressing b (add_bookmark command) and then entering a textual desciption of the bookmark in the opened menu.

  • You can open a searchable list of the bookmarks in the current document by entering gb (goto_bookmark command).

  • You can open a searchable list of all the bookmarks in all documents by entering gB (goto_bookmark_g command).

  • You can delete the closest bookmark to the current location by entering db. You can also delete bookmarks directly in the bookmarks list by selecting the bookmark and then pressing the delete button on keyboard.

Highlights

_images/highlights.png

You can highlight text in sioyek. Similar to marks, you can assign a “type” to each highlight using a lower case alphabet letter. Highlights of different types are distinguished by different colors.

  • Select a piece of text and then press h followed by a letter to create a highlight of that letter type. For example in order to create a highlight of tye “a” enter ha. (add_highlight command)

  • Press gh to open a searchable list of the highlights in the current document. (goto_highlight command)

  • Press gH to open a searchable list of the highlights ina all documents. (goto_highlight_g command)

  • In order to delete a highlight, first left click on the highlight and then enter dh (delete_highlight command). Alternatively, you can press the delete button on the keyboard in the highlight list.

Portals

_images/portals.png

Sometimes, a paragraph is entirely about a previous part of the document. For example maybe the paragraph is explaining the data in a previous table or describing a previous figure or answering a previous exercise. In such situations, it is usually very annoying to keep alternating between the paragraph and the referenced material. Using portals, you can link the location of the paragraph with the location of the referenced material and whenever you scroll to the paragraph, the referenced content is automatically displayed in a secondary window.

  • In order to create a portal, press p (link command, note that portals are called “links” in the sioyek source code, however, in the documentation we refer to them as portal so as not to confuse them with PDF links). This creates an incomplete portal with the current location as the source. Now, navigate to the location of the referenced materail and press p again. This completes the portal with the second location as the destination.

  • Alternatively, you can create portals by pressing p and then clicking on a PDF link. This automatically creates a portal from the location of the link to the link destination. Also you can middle click after pressing p which uses SmartJump to determine the destination.

  • To view portal destinations, you need to open the helper window. You can open/close the helper widow by pressing f12 (toggle_one_window command). This window automatically shows the destination of the portal with the closest source to the current location. This window is more useful for users with multiple monitors.

  • You can delete the closest portal by entering dp (delete_link command)

  • You can go to the destination of the closest link by pressing tab (goto_link command).

  • In order to edit the destination of the current link, press Shift p (edit_link command). This automatically jumps you to the destination of the link. Now you can adjust the screen or zoom level. When you are done, return to the source location by going back in history (backspace by default).

  • You can also edit the link destination by directly panning the helper window using mouse or scrolling using the mouse wheel. You can also adjust the zoom level using the mouse wheel while holding Ctrl.

Command Menu

You can open the command menu by pressing : (command command). This is a searchable list of all the commands available in sioyek (including all the commands described above) along with their current keybindings. Note that some commands do not have any keybindings. The only way to execute these commands is using the commands menu.

Synctex

  • Press f4 to toggle synctex mode. While in this mode, right clicking on any text opens the corresponding tex file in the appropriate location.

  • You can configure the synctex inverse search command using inverse_search_command config in prefs.config . Here is an example for VsCode (%1 stands for the name of the file and %2 stands for the line number in the file):

    inverse_search_command "C:\path\to\vscode\Code.exe" -r -g %1:%2
    
  • Here is a sample configuration for latex workshop in VSCode:

    "latex-workshop.view.pdf.external.synctex.command": "C:\\path\\to\\sioyek.exe",
    "latex-workshop.view.pdf.external.synctex.args": [
    "--inverse-search",
     "\"C:\\path\\to\\vscode\\Code.exe\" -r -g %1:%2",
     "--reuse-instance",
     "--forward-search-file",
     "%TEX%",
     "--forward-search-line",
     "%LINE%",
     "%PDF%" ]
    
  • Here is a sample configuration for VimTex:

    let g:vimtex_view_general_viewer = 'sioyek'
    let g:vimtex_view_general_options = '--reuse-instance'
          \ . ' --inverse-search'
          \ .   '"nvim --headless -c \"VimtexInverseSearch %2 ''%1''\""'
          \ . ' --forward-search-file @tex --forward-search-line @line @pdf'
    let g:vimtex_view_general_options_latexmk = '--reuse-instance'
    

Data and Synchronization

Sioyek stores your data in two database files named local.db and shared.db. As the name suggests, local.db stores system-specific data (for example the location of PDF files in your filesystem) while shared.db stores all other data including marks, bookmarks, portals, etc. As the name suggests, shared.db can be shared across machines. There is also a shared_database_path config which you can set in your prefs_user.config which specifies the path of this shared database file. For example you can set this path to be a file in your dropbox directory and this way all your data will automatically be synchronized across your machines.

You can also export/import your data into/from a json file by executing the export/import command (see Commands).

Miscellaneous

  • Copy text by first selecting it and pressing <Ctrl c>. (copy command)

  • You can open the links in PDF files from keyboard by pressing f and entering the number next to the desired link. (open_link command)

  • Toggle fullscreen mode using f12 (toggle_fullscreen command)

  • Press f8 to toggle dark mode. (toggle_dark_mode command)

  • Press f5 to toggle presentation mode.