Configuration file

Papis uses a configuration file in INI format. This configuration file will usually be located in ~/.config/papis/config (on Linux) or similar locations on other platforms.

In the Papis configuration file, the main entries will be sections describing what libraries you have. For example, assume you have two libraries: a library called papers and another called books. In general, these libraries work and can be configured independently from each other.

In the simplest case, you would simply need to declare their location in your system, like so

[settings]
default-library = papers

# my library for papers and stuff
[papers]
dir = ~/Documents/papers

# my library for books and related documents
[books]
dir = ~/Documents/books

The [settings] section is used to set global configuration options. However, an important aspect of the configuration system is that you can override settings on a per library basis. This means that you can set options with different values for each of your libraries, depending on the use case you had in mind. For example, let’s suppose you want to open your documents from papers using the PDF reader okular however in books you want to open the documents in firefox (for some reason). Then, you would add the following lines to your configuration

[settings]
opentool = evince
default-library = papers

# my library for papers and stuff
[papers]
dir = ~/Documents/papers
opentool = okular

# my library for books and related documents
[books]
dir = ~/Documents/books
opentool = firefox

Here we also added the opentool setting the global section [settings]. With this configuration file, the two shown libraries will open documents with their respective tool, while any other library will default to evince. There are many configuration options and you can check their values using the papis config command, e.g.

# show all the current options in the [settings] section
papis config --section settings
# show the default options
papis config --default --section settings
# show the value of the 'opentool' option for the books library
papis -l books config opentool

A more complete example of a configuration file is the following (see General Settings for a comprehensive list of all the options and more extensive descriptions)

Warning

Many configuration options use special formatted strings that can depend on the document that is being worked on. When using these, make sure to also set the formatter to your desired choice. Below, we are using the default python formatter that is based on str.format().

#
# This is a general section, the settings set here will be global for
# all libraries
#
[settings]
# General file opener program ("rifle" is a nice general opener). This
# setting should be platform dependent, so on macOS you can use "open",
# on Linux you can use "xdg-open", on Windows you can set it to "cygstart"
# (under Cygwin at least), etc.
opentool = rifle
# Use "ranger" as a file browser
file-browser = ranger

# Ask for confirmation when doing "papis add" before adding to the library.
# Equivalent to "papis add --confirm".
add-confirm = True
# Edit the "info.yaml" file before adding a document to the library.
# Equivalent to "papis add --edit".
add-edit = True
# Open any document files before adding the document to the library.
# Equivalent to "papis add --open".
add-open = True

# Define custom default match formats. This format is used when searching
# documents in the default picker.
match-format = {doc[tags]}{doc.subfolder}{doc[title]}{doc[author]}{doc[year]}
# Define header format with colors and multiline support. This formatting
# will be used when displaying a document in the default picker.
header-format = <red>{doc.html_escape[title]}</red>
  <span color='#ff00ff'>  {doc.html_escape[author]}</span>
  <yellow>   ({doc.html_escape[year]})</yellow>

# Set options for the default picker and other CLI widgets.
[tui]
editmode = vi
options_list.selected_margin_style = bg:ansigreen fg:ansired
options_list.unselected_margin_style =

# Define a library for papers
[papers]
dir = ~/Documents/papers

# Override settings from the "tui" section only for the "papers" library.
# When using settings from another settings, the section name needs to be
# prepended -- here we prepend "tui-" to the settings.
tui-editmode = emacs
tui-options_list.unselected_margin_style = bg:blue

# Use whoosh as a database for "papers".
database-backend = whoosh
# Rename files added by author and title in "papis add"
add-file-name = {doc[author]}{doc[title]}

# Define a library for books.
[books]
dir = ~/Documents/books
database-backend = whoosh

# Define a library for videos.
[videos]
dir = ~/Videos/courses

# Define a lib for contacts (why not?). To make it work you just have to
# define some sane settings.
[contacts]
dir = ~/contacts/general
database-backend = papis

match-format = {doc[org]} {doc[first_name]} {doc[last_name]}
header-format = {doc[first_name]} {doc[last_name]}

browse-query-format = {doc[first_name]} {doc[last_name]}
add-open = False

Local configuration files

Papis also offers the possibility of creating local configuration files. The name of the local configuration file can be configured with the local-config-file setting. The local configuration files are looked for in the current directory (where the papis command is issued) or in the directory of the current library.

For instance, suppose that you are in some project folder ~/Documents/myproject and you have a local config file there with a definition of a new library project. Then, whenever you are in the ~/Documents/myproject directory, Papis will also read the local configuration file and you will have access to the additional library project.

On the other hand, if you have a configuration file in the folder for your papers, for instance in:

~/Documents/papers/.papis.config

Then, every time that you use this library Papis will also source this configuration file. This can be used as an alternative to adding more configuration options in the main configuration file or if you expect this library to be used on more machines with different configurations.

An example of a project using a local configuration file can be seen here. The repository includes documents for component datasheets and every time papis is using that library the .papis.config file is also read and some settings will get overridden.

Python configuration file

For some more dynamic use cases, it would be useful to have a Python file that gets loaded together with the usual configuration file. This file lives in your Papis configuration directory and has the name config.py. For instance, for most users it will be in:

~/.config/papis/config.py

General settings

local-config-file
Type:

str

Default:

'.papis.config'

Relative path of the local configuration file that Papis will additionally read. The file must be present in the current directory or in the base directory of a given library.

This can be used to set special configuration settings for a library that do not clutter your global configuration file. This is particularly useful if the library is shared with someone else (or just on a different machine) and you want them to have the same settings. For example, say you’re sharing a library with your friend Fulano. You have your library at:

~/Documents/lib-with-fulano

and you’ve created a local configuration file at:

~/Documents/lib-with-fulano/.papis.config

Then, you can share your library (through e.g. Dropbox or a network drive) and have the same settings for the library across machines, e.g. to generate consistent references with ref-format. In this setup, whenever Fulano uses that library, their Papis calls will also read the configuration settings and use the same settings.

dir-umask
Type:

int

Default:

493

This is the default os.umask() that will be used to create the new directories for documents and libraries.

use-git
Type:

bool

Default:

False

Some commands will issue git commands if this option is set to True. For example papis mv or papis rename can automatically commit any changes to a document by default. See Git support for additional details.

user-agent
Type:

str

Default:

'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_3)'

User agent used by Papis whenever querying information from external sources.

scripts-short-help-regex
Type:

str

Default:

'.*papis-short-help: *(.*)'

This is the format of the short help indicator in external Papis commands. In general, for an external command, the first lines are expected to resemble

#!/usr/bin/env python3
# papis-short-help: My awesome script fixes everything
info-name
Type:

str

Default:

'info.yaml'

The default name for files containing the document metadata. In Papis, these are referred to as info files (see The info.yaml file) and contain metadata in the YAML format.

doc-url-key-name
Type:

str

Default:

'doc_url'

Some documents might have multiple URLs associated with them, e.g. remote URLs from different sources or a file URL. This setting can be used to choose which one is more appropriate to use in different settings, e.g. the Crossref importer uses it to download files.

default-library
Type:

str

Default:

'papers'

The name of the library that is to be used when Papis is run without the -l/--lib argument. Papis will not immediately check if this library exists in the configuration file or that it is correctly configured.

format-doc-name
Type:

str

Default:

'doc'

This setting controls the name of the document in the Papis format strings like in format strings such as match-format or header-format. For instance, if you are managing videos, you might want to set this option to vid in order to set the header-format to

header-format = {vid[title]} - {vid[director]} - {vid[duration]}.
match-format
Type:

str

Default:

'{doc[tags]}{doc.subfolder}{doc[title]}{doc[author]}{doc[year]}'

Default format that is used to match a document in the default Papis picker and in the papis database backend. For example, if the match-format is set to {doc[year]} {doc[author]}, then words from the title will not match the document, only using the year or the author will work. It is recommended to set this to all the keys used by header-format, so that any visible information can be matched.

header-format
Type:

str

Default:

'<ansired>{doc.html_escape[title]}</ansired>\n <ansigreen>{doc.html_escape[author]}</ansigreen>\n  <ansiblue>({doc.html_escape[year]})</ansiblue> [<ansiyellow>{doc.html_escape[tags]}</ansiyellow>]'

Default format that is used to show a document in the default Papis picker. This can be a complex multiline string containing any key from a document.

header-format-file
Type:

str

Default:

None

If the header-format grows too complex, it can be stored in a separate file. This option should give the path to that file (in which case the header-format option will be ignored). For example, this can be set to

header-format-file = ~/.config/papis/styles/header-format.txt
info-allow-unicode
Type:

bool

Default:

True

If True, this flag will allow unicode characters in your info files. Otherwise, the strings will be decoded and written as bytes. Unless you have very strong reasons not to, this should always be set to True (we live a unicode world after all!).

unique-document-keys
Type:

str

Default:

"['doi','ref','isbn','isbn10','url','doc_url']"

Whenever you add a new document, Papis tries to figure out if you have already added this document before. This is partially done checking for matches in some special keys. This setting controls which keys are checked.

For instance, if you add a paper with a given doi, and then you add another document with the same doi, then Papis will notify you that there is already another document with this doi because the doi key is part of the unique-document-keys option.

document-description-format
Type:

str

Default:

'{doc[title]} - {doc[author]}'

Papis sometimes will have to tell you which document it is processing. This format string can be used to display the document to the user in a non-intrusive way. Preferable, this should be a short string that allows easily identifying which document is being referenced.

sort-field
Type:

str

Default:

None

This setting controls which field queries are sorted by before being presented to the user in, e.g., the picker. Most commands support a --sort option that uses this setting as its default value.

sort-reverse
Type:

bool

Default:

False

A setting that augments sort-field by allowing the documents to be sorted in reverse order. Most commands support a --reverse flag that uses this setting as a default value.

formatter
Type:

str

Default:

'python'

Picks the formatter for templated strings in the configuration file and in various strings presented to the user. Supported formatters are

Note that the default values of many of the Papis configuration settings are based on the Python formatter. These will need to all be specified explicitly if another formatter is chosen.

Note The older (misspelled) version "formater" is deprecated.

doc-paths-lowercase
Type:

bool

Default:

True

This setting controls whether capital letters in a (generated or specified) document path should be lowercased before the path is created.

doc-paths-extra-chars
Type:

str

Default:

''

By default document paths in Papis libraries can contain only a limited set of characters. This is mainly to exclude characters that are invalid for file paths on any operating system or possibly unprintable. Allowed characters are:

  • latin letters (a to z)

  • arabic digits (0 to 9)

  • dots (for file extensions)

  • directory separators (usually / on UNIX-like systems and \\ on Windows)

This setting allows to append additional characters to this set. It expects a string containing all additional valid characters. A possible value would be "_" to allow underscores in document paths.

doc-paths-word-separator
Type:

str

Default:

'-'

This setting defines the separator between words in document paths (usually replacing spaces or other non-letter characters). By default this is the hyphen "-" but it could, e.g., also be the underscore "_".

Tools options

opentool
Type:

str

Default:

'xdg-open'

This is a general program that will be used to open document files. Papis is not intended to detect the type of file that is being opened or decide on how to open the document. Therefore, the opentool should handle this functionality. If you are on Linux, you might want to take a look at ranger or just use xdg-open. For macOS users, this should likely be set to open.

browser
Type:

str

Default:

'$BROWSER'

Program to be used for opening websites, the default is the environment variable $BROWSER.

picktool
Type:

str

Default:

'papis'

This is the program used whenever Papis asks to pick a document for a query, pick a file to open, or any other such use case with multiple options. The following pickers are available:

  • "papis": uses papis.picker.Picker to display and search through documents.

  • "fzf": uses fzf <https://github.com/junegunn/fzf> to display and search through documents.

Papis pickers use a plugin architecture similar to other components (see Plugin architecture) with the papis.picker entrypoint. Note that not all plugins will support all the same features.

editor
Type:

str

Default:

'$EDITOR'

Editor used to edit files in Papis, e.g., for the papis edit command. This will search for the $EDITOR environment variable or the $VISUAL environment variables to obtain a default if it is not set. Otherwise, the default opentool will be used.

file-browser
Type:

str

Default:

'xdg-open'

File browser used when opening a directory. It defaults to the default file browser in your system. However, you can set it to different file browsers, such as dolphin, thunar or ranger, to name a few.

BibTeX options

bibtex-journal-key
Type:

str

Default:

'journal'

This option allows the user to set the key for the journal entry when using papis export --bibtex. The intended use of such a setting is to allow selecting e.g. abbreviated journal titles for publishers that require it. For example, if the document has a abbrev_journal_title key that should be used instead of the default journal key.

extra-bibtex-keys
Type:

str

Default:

'[]'

A list of additional keys, besides the known standard BibTeX keys from bibtex_keys, to add to the BibTeX export. This can be used to include keys such as doc_url or tags to the export by setting

[mylib]
extra-bibtex-keys = ["doc_url", "tags"]

These keys will likely not be recognized by the BibTeX engine, so they should be used with care. However, they can be useful when exporting documents as a form of backup to be imported in another library later.

bibtex-ignore-keys
Type:

str

Default:

'[]'

A list of keys that should be ignored when exporting to BibTeX. This might be useful if you have some keys that have a lot of content, such as abstract, or maybe you have used a valid BibTeX key for some other purpose, like the note key.

extra-bibtex-types
Type:

str

Default:

'[]'

A list of additional types, besides the known standard BibTeX types from bibtex_types, that should be allowed for a BibTeX export. These types can be added as

[mylib]
extra-bibtex-types = ["wikipedia", "video", "song"]
bibtex-unicode
Type:

bool

Default:

False

A flag used to choose whether or not to allow direct Unicode characters in the document fields to be exported into the BibTeX text. Some engines, such as Biber support Unicode by default and should be used whenever possible.

bibtex-export-file
Type:

bool

Default:

False

A flag that can be used to add a "file" field to exported BibTeX entries. The files are added as a semicolon separated string.

This entry used to be named bibtex-export-zotero-file and should be used instead.

multiple-authors-format
Type:

str

Default:

'{au[family]}, {au[given]}'

A format string for concatenating author fields into a string that can be used for display purposes or for building the author key for the document. For example, when retrieving automatic author information from services like Crossref, Papis builds the author using this setting. For instance, this can be set to

multiple-authors-format = {au[family]} -- {au[given]}

which for the author {"family": "Einstein", "given": "Albert"} would construct the string Einstein -- Albert. In most circumstances, multiple authors are then concatenated together using multiple-authors-separator.

multiple-authors-separator
Type:

str

Default:

' and '

A string used with multiple-authors-format to concatenate multiple authors, e.g. into the authors document key. By default, this is set to and, which is the separator used by BibTeX in its so-called name-lists.

BibTeX command options

default-read-bibfile
Type:

str

Section:

bibtex

Default:

''

A path to a BibTex file that should be automatically read when using the papis bibtex command. This should be equivalent to using papis bibtex read file.bib when used with auto-read.

default-save-bibfile
Type:

str

Section:

bibtex

Default:

''

A path to a BibTex file that should be automatically saved when using the papis bibtex command. This should be equivalent to using papis bibtex save file.bib.

auto-read
Type:

str

Section:

bibtex

Default:

''

A flag used in conjunction with default-read-bibfile to automatically read a BibTeX file.

Add options

ref-format
Type:

str

Default:

'{doc[title]:.15} {doc[author]:.6} {doc[year]}'

This option is used to set the ref key in the info file when a document is created. In BibLaTeX, the reference (or ref for short) is also sometimes called a citation key. The reference format is usually heavily customized by users, depending on their personal preferences. For example to use a FirstAuthorYear format, set

ref-format = {doc[author_list][0][family]}{doc[year]}

However, any custom string can be used, e.g.

ref-format = {doc[title]:.15} {doc[author]:.6} {doc[year]}

The resulting reference is also cleaned up by Papis to ensure that no invalid characters make it into final version. If a reference does not exist in the document, it is created using papis.bibtex.create_reference(). Any reference is then cleaned up using papis.bibtex.ref_cleanup().

Warning

Note that the reference clean up can result in a heavily modified version compared to the string that was set by the ref-format option. For example, all spaces are transformed into underscores and all unicode characters are converted to their closest ASCII representation.

If you want to add some punctuation, dots (.) and underscores (_) can be escaped by a backslash. For example,

ref-format = {doc[author_list][0][surname]}\.{doc[year]}
add-folder-name
Type:

str

Default:

''

Set the default name for the folder of newly added documents. For example, if you want the folder of your documents to be named after the format author-title then you should set it to

add-folder-name = ``{doc[author]}-{doc[title]}``

You can create formatted subfolders by using path separators (i.e., /) in this format string, e.g.

add-folder-name = ``{doc[year]} / {doc[author]}-{doc[title]}``

If this setting is empty, a (MD5) hash of some document contents followed by the author names is used. This will generally result in unique folder names. If a folder name is not unique and the document does not appear to be a duplicate, a suffix -a, -b, etc. is added to the names.

add-file-name
Type:

str

Default:

None

Set the default file name for newly added documents, similarly to add-folder-name. If it is not set, the names of the files will be cleaned and taken as-is.

add-subfolder
Type:

str

Default:

''

Configure a default for the --subfolder command-line option of papis add. Note that, this setting is not allowed to contain formatting options. However, one can also specify nested sub-folders.

add-confirm
Type:

bool

Default:

False

A setting that controls the default for the --confirm flag of papis add. If set to True, then the flag will be added by default and additional confirmation will be asked for when adding the document. In this case, the confirmation can be turned off using --no-confirm on an individual basis.

add-edit
Type:

bool

Default:

False

A setting that controls the default for the --edit flag of papis add. If set to True, then the flag will be added by default and an editor will be opened before the document is saved for additional modifications. In this case, the edit can be disabled using --no-edit on an individual basis.

add-open
Type:

bool

Default:

False

A setting that controls the default for the --open flag of papis add. If set to True, then the flag will be added by default and a viewer will be opened to allow checking every file added to the document. In this case, the open can be disabled using --no-open on an individual basis.

add-download-files
Type:

bool

Default:

True

A setting that controls the default for the --download-files flag of papis add. If set to True, then the flag will be added by default and the selected importers and downloaders will attempt to also download files (metadata is always downloaded). In this case, the download can be disabled by using --no-download-files on an individual basis.

add-fetch-citations
Type:

bool

Default:

False

A setting that controls the default for the --fetch-citations flag of ``papis add. If set to True, then the flag will be added by default and Papis will attempt to retrieve citations for the newly added document. In this case, the fetching can be disabled by using --no-fetch-citations on an individual basis.

auto-doctor
Type:

bool

Default:

False

A setting that controls the default for the --auto-doctor flag of papis add and papis update. If set to True, then the flag will be enabled by default and the doctor fixes will be applied to new documents. In this case, the automatic fixers can be disabled by using --no-auto-doctor on an individual basis.

time-stamp
Type:

bool

Default:

True

A setting that controls if a timestamp is added to a document on papis add. The timestamp uses the standard ISO format and can be used for sorting and querying like any other fields.

Browse options

browse-key
Type:

str

Default:

'auto'

This setting provides the key that is used to generate a URL for the papis browse command. In the simplest case, browse-key is just a key in the document (e.g. url) that contains a URL to open. It also supports the following special values:

  • "doi": construct a URL from the DOI as https://dx.doi.org/<DOI>.

  • "isbn": construct a URL from the ISBN as https://isbnsearch/isbn/<ISBN>.

  • "ads": construct a URL for the Astrophysics Data System as https://ui.adsabs.harvard.edu/abs/<DOI>.

  • "auto": automatically pick between url, doi and isbn (first existing key is chosen).

  • "search-engine": the search-engine is used to search for the contents of browse-query-format.

If the required keys are not found in the document (e.g. the DOI or the ISBN), the key will fallback to the "search-engine" case.

browse-query-format
Type:

str

Default:

'{doc[title]} {doc[author]}'

The query string that is to be searched for in the papis browse command whenever a search engine is used (see browse-key).

search-engine
Type:

str

Default:

'https://duckduckgo.com'

Search engine to be used by some commands like papis browse. This should be a base URL that is then used to construct a search as <BASE>/?<PARAMS>.

Edit options

notes-name
Type:

str

Default:

'notes.tex'

In papis edit you can edit notes about the document. notes-name is the default name of the notes file. The notes-name is formatted by the formatter, so that the filename of notes can be dynamically defined, e.g.:

notes-name = notes_{doc[ref]}.rst
notes-template
Type:

str

Default:

''

When editing notes for the first time, a preliminary notes file will be generated based on a template. The path to this template is specified by notes-template. The template will then be formatted by formatter. This can be useful to enforce the same style in the notes for all documents.

Default value is set to the empty "", which will return an empty notes file. If no file is found at the path to the template, then also an empty notes file will be generated.

Doctor options

doctor-default-checks
Type:

List [str]

Default:

['files', 'keys-exist', 'duplicated-keys']

A list of checks that are performed by default.

doctor-keys-exist-keys
Type:

List [str]

Default:

['title', 'author', 'author_list', 'ref']

A list of keys used by the keys-exist check. The check will show an error if these keys are not present in a document.

doctor-duplicated-keys-keys
Type:

List [str]

Default:

['ref']

A list of keys used by the duplicated-keys check. The check will show an error if the value of these keys is duplicated across multiple documents.

doctor-duplicated-values-keys
Type:

List [str]

Default:

['files', 'author_list']

A list of keys used by the duplicated-values check. The check will show an error if any of the keys listed here have repeated values. This can check, e.g., if a file was mistakenly added multiple times or if a tag already exists in the document.

doctor-html-codes-keys
Type:

List [str]

Default:

['title', 'author', 'abstract', 'journal']

A list of keys used by the html-codes check. The check will show an error if any of the keys contain unwanted HTML codes, e.g. &amp;.

doctor-html-tags-keys
Type:

List [str]

Default:

['title', 'author', 'abstract', 'journal']

A list of keys used by the html-tags check. The check will show an error if any of the keys contain unwanted HTML tags, e.g. <div>.

doctor-key-type-check-keys
Type:

List [str]

Default:

['year:int', 'month:int', 'files:list', 'notes:str', 'author_list:list', 'doi:str', 'ref:str', 'isbn:str', 'author:str', 'journal:str', 'note:str', 'type:str', 'publisher:str', 'title:str', 'shorttitle:str']

A list of strings key:type used by the key-type check. This check will show an error if the key does not have the corresponding type. The type should be a builtin Python type. For example, this can be ["year:int", "tags:list"] to check that the year is an integer and the tags are given as a list in a document.

doctor-key-type-check-separator
Type:

str

Default:

None

A separator used by the key-type check fixer. When converting from str to list, it is used to split the string into a list, and when converting from list to str, it is used to join list items. The split will ignore additional whitespace around the separator (for instance, when set to ,, the string "extra,    whitespace" will be converted to the list ["extra", "whitespace"]). To preserve leading or trailing whitespace in the separator, make sure to quote it (for instance, ", ").

Open options

open-mark
Type:

bool

Default:

False

A setting that controls the default for the --mark flag of papis open. If set to True, then the flag will be added by default and the mark will be opened for editing. In this case, the open can be disabled using --no-mark on an individual basis.

mark-key-name
Type:

str

Default:

'marks'

This is the default key name for the marks in the info file. For example, if you set mark-key-name = bookmarks then you would have in your info.yaml file

author: J. Krishnamurti
bookmarks:
- name: Chapter 1
  value: 120
mark-format-name
Type:

str

Default:

'mark'

This is the name of the mark to be passed to mark-header-format and other such settings, similarly to format-doc-name. For example, if we want to set it to m, then other settings must be consistent, e.g.

mark-format-name = m
mark-header-format = {m[value]} - {m[name]}
mark-header-format
Type:

str

Default:

'{mark[name]} - {mark[value]}'

This is the format of the mark when shown in a picker, similarly to header-format. This can be changed to allow for more complex marks. However, by default, we just assume that each mark is of the form {"name": <NAME>, "value": <VALUE>}.

mark-match-format
Type:

str

Default:

'{mark[name]} - {mark[value]}'

Format in which the mark name has to match the user input, similarly to match-format.

mark-opener-format
Type:

str

Default:

'xdg-open'

Due to the difficulty to generalize opening a general document at a given bookmark, the user should set this to whatever suits their needs. For example

  • If you are using the PDF viewer evince and you want to open a mark, you would use:

    mark-opener-format = evince -p {mark[value]}

  • If you are using okular you would use:

    mark-opener-format = okular -p {mark[value]}

  • If you are using zathura, then use:

    mark-opener-format = zathura -P {mark[value]}

Serve (Web App) options

serve-default-tag-sorting
Type:

str

Default:

'numeric'

The default sorting strategy used on the “Tags” tab of the Web UI. Can be either 'alpha' for sorting by tags’ names or 'numeric' for sorting by their frequency of use.

serve-empty-query-get-all-documents
Type:

bool

Default:

False

If True, when no documents are found by a query then all documents are shown instead. By default this is false, since showing all the documents can be slow.

serve-enable-timeline
Type:

bool

Default:

False

If True, the time-stamp of documents is used to create a timeline for when the documents were added.

serve-timeline-max
Type:

int

Default:

500

Maximum number of documents to display in the timeline.

Frameworks

All the frameworks used by the web UI are taken from the configuration file. This allows users to easily provide newer versions that may fix some bugs or other inconsistencies.

Warning

Updating the URLs for one of the frameworks may result in a broken UI, as Papis is not compatible with all versions. For safety only update minor bugfix releases, not major new updates.

serve-user-css
Type:

list

Default:

[]

A list of href URLs that will be added to the header of each webpage of the web UI. These style sheets are added to the end and can be used to overwrite previous entries.

serve-user-js
Type:

list

Default:

[]

A list of href URLs that will be added to the header of each webpage of the web UI. These scripts are added to the end and can be used to overwrite previous entries.

serve-bootstrap-css
Type:

str

Default:

'https://cdn.jsdelivr.net/npm/bootstrap@5.1.1/dist/css/bootstrap.min.css'

Link to the desired version of the Bootstrap framework.

serve-bootstrap-js
Type:

str

Default:

'https://cdn.jsdelivr.net/npm/bootstrap@5.1.1/dist/js/bootstrap.bundle.min.js'

Link to the desired version of the Bootstrap framework.

serve-jquery-js
Type:

str

Default:

'https://code.jquery.com/jquery-3.6.0.min.js'

Link to the desired version of the jQuery framework.

serve-jquery.dataTables-css
Type:

str

Default:

'https://cdn.datatables.net/v/bs5/dt-1.13.1/kt-2.8.0/sc-2.0.7/sb-1.4.0/datatables.min.css'

Link to the desired version of the jQuery DataTables framework.

serve-jquery.dataTables-js
Type:

str

Default:

'https://cdn.datatables.net/v/bs5/dt-1.13.1/kt-2.8.0/sc-2.0.7/sb-1.4.0/datatables.min.js'

Link to the desired version of the jQuery DataTables framework.

serve-katex-css
Type:

str

Default:

'https://cdn.jsdelivr.net/npm/katex@0.16.4/dist/katex.min.css'

Link to the desired version of the KaTeX framework.

serve-katex-js
Type:

str

Default:

'https://cdn.jsdelivr.net/npm/katex@0.16.4/dist/katex.min.js'

Link to the desired version of the KaTeX framework.

serve-katex-auto-render-js
Type:

str

Default:

'https://cdn.jsdelivr.net/npm/katex@0.16.4/dist/contrib/auto-render.min.js'

Link to the desired version of the

KaTeX Auto-render extension.

serve-ace-urls
Type:

List [str]

Default:

['https://cdnjs.cloudflare.com/ajax/libs/ace/1.14.0/ace.min.js', 'https://cdnjs.cloudflare.com/ajax/libs/ace/1.14.0/mode-yaml.min.js', 'https://cdnjs.cloudflare.com/ajax/libs/ace/1.14.0/mode-bibtex.min.js', 'https://cdnjs.cloudflare.com/ajax/libs/ace/1.14.0/mode-markdown.min.js', 'https://cdnjs.cloudflare.com/ajax/libs/ace/1.14.0/mode-latex.min.js', 'https://cdnjs.cloudflare.com/ajax/libs/ace/1.14.0/ext-textarea.min.js', 'https://cdnjs.cloudflare.com/ajax/libs/ace/1.14.0/ext-settings_menu.min.js', 'https://cdnjs.cloudflare.com/ajax/libs/ace/1.14.0/ext-keybinding_menu.min.js', 'https://cdnjs.cloudflare.com/ajax/libs/ace/1.14.0/keybinding-vim.min.js', 'https://cdnjs.cloudflare.com/ajax/libs/ace/1.14.0/keybinding-emacs.min.js']

A list of links to the desired version of the Ace editor. This should contain all necessary links to all the desired modes and keybindings, as exemplified by the default values.

serve-timeline-css
Type:

str

Default:

'https://cdn.knightlab.com/libs/timeline3/latest/css/timeline.css'

Link to the desired version of the Timeline widget.

serve-timeline-js
Type:

str

Default:

'https://cdn.knightlab.com/libs/timeline3/latest/js/timeline.js'

Link to the desired version of the Timeline widget.

Citations options

You can change the name of the citation files, however we discourage this.

citations-file-name
Type:

str

Default:

'citations.yaml'

The name of the file to store the citations of the documents.

cited-by-file-name
Type:

str

Default:

'cited-by.yaml'

The name of the file to store the citations to the document.

Downloaders

downloader-proxy
Type:

str

Default:

None

There is the possibility of download papers using a proxy. We use requests to handle web queries, which has extensive documentation on how to use proxies here. This value should give a URL that can be used as a proxy for both HTTP and HTTPS.

isbn-service
Type:

str

Default:

'openl'

Sets the ISBN service used by the ISBN importer. Available plugins are documented here.

Databases

default-query-string
Type:

str

Default:

'.'

This is the default query that a command will take if no query string is given at the command line. For example, if you want to open all papers authored by John Smith whenever you do not specify an input query string, then setting:

default-query-string = author:"John Smith"

would do the trick. Note that each database-backend will have a different search query, so this setting is specific to the default papis backend.

database-backend
Type:

str

Default:

'papis'

The backend to use in the database. The database is used to store the document in a library for improved querying performance and can be better thought of as a cache. The supported backends are

  • "papis": a backend that uses the pickle format as a storage format and has a query syntax based on papis.docmatcher.

  • "whoosh": a backend that uses whoosh. for its storage and querying needs.

use-cache
Type:

bool

Default:

True

If set to False, then no database caching layer is used. This is only effective when using the papis backend and disables the storage aspects, while keeping the query syntax.

If the cache is disabled, then every call to papis commands will have to walk the library directory tree to gather all the documents. This can be very slow for large libraries.

cache-dir
Type:

str

Default:

'$XDG_CACHE_HOME'

The default directory where the cache for the papis backend is stored.

whoosh-schema-fields
Type:

str

Default:

"['doi']"

Python list with the TEXT fields that should be included in the whoosh database schema. For instance, say that you want to be able to search for the doi and ref of the documents, then you could include:

whoosh-schema-fields = ['doi', 'ref']
whoosh-schema-prototype
Type:

str

Default:

'{\n"author": TEXT(stored=True),\n"title": TEXT(stored=True),\n"year": TEXT(stored=True),\n"tags": TEXT(stored=True),\n}'

This is the model for the whoosh schema, check the documentation for more information. The resulting string is passed to eval(), so care should be taken when modifying it.

Terminal user interface (picker)

These options are for the terminal user interface (TUI). The TUI is mainly used by the default Papis picker, but other small widgets also make use of some elements. The TUI can be heavily customized as well in the separate tui section. For example,

[tui]
status_line_format = "F1: Help"

These settings are based on styling and options used by prompt_toolkit, so their documentation should be consulted.

Styling

For styling the individual components, see the extensive documentation available here.

status_line_format
Type:

str

Section:

tui

Default:

'{selected_index}/{number_of_documents}  F1:help  c-l:redraw  '

This is the format of the string that appears at the bottom in the picker status line. Right now there are only two variables defined: selected_index and number_of_documents.

status_line_style
Type:

str

Section:

tui

Default:

'bg:ansiwhite fg:ansiblack'

The style the status line should based on the prompt_toolkit styling, e.g.``fg:#ff00aa bg:black``.

message_toolbar_style
Type:

str

Section:

tui

Default:

'bg:ansiyellow fg:ansiblack'

The style of the message toolbar. This toolbar is the one where messages of the echo command are rendered.

options_list.selected_margin_style
Type:

str

Section:

tui

Default:

'bg:ansiblack fg:ansigreen'

Style of the margin of the selected document in the picker.

options_list.unselected_margin_style
Type:

str

Section:

tui

Default:

'bg:ansiwhite'

Style of the margin of the unselected documents in the picker. If no styling is desired on these elements, this setting can be empty.

options_list.marked_margin_style
Type:

str

Section:

tui

Default:

'bg:ansiblack fg:ansiwhite'

Style of the margin of the marked documents in the picker. If no styling is desired on these elements, this setting can be empty.

error_toolbar_style
Type:

str

Section:

tui

Default:

'bg:ansired fg:ansiblack'

The style for the error message toolbar.

editmode
Type:

str

Section:

tui

Default:

'emacs'

Controls keybindings when typing text in various TUI widgets. This can be set to either emacs or vi type keybindings. If this does not tell you anything, you can just leave it as is.

Key bindings

For information about keybindings, see the corresponding documentation.

move_down_key
Type:

str

Section:

tui

Default:

'down'

move_up_key
Type:

str

Section:

tui

Default:

'up'

move_down_while_info_window_active_key
Type:

str

Section:

tui

Default:

'c-n'

move_up_while_info_window_active_key
Type:

str

Section:

tui

Default:

'c-p'

focus_command_line_key
Type:

str

Section:

tui

Default:

'tab'

edit_document_key
Type:

str

Section:

tui

Default:

'c-e'

open_document_key
Type:

str

Section:

tui

Default:

'c-o'

show_help_key
Type:

str

Section:

tui

Default:

'f1'

show_info_key
Type:

str

Section:

tui

Default:

's-tab'

go_top_key
Type:

str

Section:

tui

Default:

'home'

go_bottom_key
Type:

str

Section:

tui

Default:

'end'

mark_key
Type:

str

Section:

tui

Default:

'c-t'

FZF integration

Papis ships with out-of-the-box fzf integration for the picker. A minimal terminal user interface is provided, together with options for its customization. You can set the picktool to fzf to select this picker.

In comparison to the built-in Papis picker TUI, the advantage of the fzf picker is that it is much faster. However, a disadvantage is that it is restricted to one-line entries. It is also important to note that fzf will only match against what is shown on the terminal screen, as opposed to the Papis matcher, that can match against the whole title and whole author text, since this is controlled by the match-format setting. However, for many uses it might not bother the user to have this limitation of fzf.

fzf-binary
Type:

str

Default:

'fzf'

Path to or name of the fzf binary.

fzf-extra-flags
Type:

List [str]

Default:

['--ansi', '--multi', '-i']

Extra flags to be passed to fzf every time it gets called.

fzf-extra-bindings
Type:

List [str]

Default:

['ctrl-s:jump']

Extra bindings to fzf as a Python list. Refer to the fzf documentation for more details.

fzf-header-format
Type:

str

Default:

'{c.Fore.MAGENTA}{doc[title]:<70.70}{c.Style.RESET_ALL} :: {c.Fore.CYAN}{doc[author]:<20.20}{c.Style.RESET_ALL}{c.Fore.YELLOW}«{doc[year]:4}»{c.Style.RESET_ALL}:{doc[tags]}'

Format for the entries for fzf. Notice that if you want colors you should add the --ansi flag to fzf-extra-flags and include the colors in the header-format as ansi escape sequences.

The Papis format string is given the additional variable c which contains the package colorama in it. Refer to the colorama documentation. to see which colors are available. For instance, if you want the title in red, you would put in your fzf-header-format

"{c.Fore.RED}{doc[title]}{c.Style.RESET_ALL}"

Preview window

fzf has the disadvantage that it does not support multiline output and it matches only against what it shows on the screen. To get around this issue, we can try composing a fzf customization. The following will add a preview window to the picker

fzf-extra-flags = ["--ansi", "--multi", "-i",
                   "--preview", "echo {} | sed -r 's/~~/\\n/g; /^ *$/d' ",
                   "--preview-window", "bottom:wrap:20%%",
                   "--color", "preview-fg:#F6E6E4,preview-bg:#5B6D5B"]

fzf-extra-bindings = ["ctrl-s:jump",
                      "ctrl-t:toggle-preview"]

fzf-header-format = {c.Fore.MAGENTA}{doc[title]}{c.Style.RESET_ALL}~~ {c.Fore.CYAN}{doc[author]}{c.Style.RESET_ALL}~~ {c.Fore.YELLOW}«{doc[year]}»{c.Style.RESET_ALL}~~ {c.Fore.YELLOW}{doc[journal]}{c.Style.RESET_ALL}~~ :{doc[tags]}

This will add unrestricted titles, author, journal etc fields against which the query will match and it will show in the fzf preview window a tidy description of the currently selected field by replacing the token ~~ by a newline. You can try this out and play with fzf customizations.

Note

Please note that bottom:wrap:20%% has two % since the config file interpolator uses % as a reserved symbol, so it must be escaped by writing two of them.