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.

For example, let’s suppose you want to open your documents from papers using the PDF reader okular. In books, however, you want to open the documents in firefox. In this case, 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 in 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 format patterns 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

Note

Papis uses the standard ConfigParser to read and write configuration options. It also allows interpolation of values (using BasicInterpolation) so that previous values can be referred back to. For example, one can do:

[DEFAULT]
basedir = /path/to/libraries

[papers]
dir = %(basedir)s/papers

[books]
dir = %(basedir)s/books

Interpolation variables are looked for in the current section and in the standard DEFAULT section.

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 patterns 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:: FormatPattern
Default:: '{doc[tags]}{doc.subfolder}{doc[title]}{doc[author]}{doc[year]}{doc[ref]}'

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:: FormatPattern
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 in a Unicode world after all!).

unique-document-keys

Type:: List [str]
Default:: ['doi', 'isbn', 'isbn10', 'eprint', '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:: FormatPattern
Default:: '{doc[title]} - {doc[author]}'

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

completion-format

Type:: FormatPattern
Default:: '{doc[ref]}'

Format for document autocompletion. It is used to construct the completion value that is given to the shell when pressing Tab after entering a search query in the command-line. For example, writing papis addto ein<TAB> will query the database for the ein string, but the completion will be constructed using completion-format from the matching documents.

completion-help-format

Type:: FormatPattern
Default:: '{doc[title]} - {doc[author]}'

Format for the tip displayed next to document completions in the command line upon pressing Tab. Not all shells support this.

prefix-only-completions

Type:: bool
Default:: False

Whether to only suggest completions that start with the inserted query. Setting this to true will only suggest e.g. einstein1905 when the query is ein but neither wittgenstein1921 nor goethe1780 with the title Ein Gleiches. This can be useful if your shell trims the query to the longest common prefix, like zsh.

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 format patterns in the configuration file and in various strings presented to the user. Supported formatters are

"python": based on papis.format.python.PythonFormatter.
"jinja2": based on papis.format.jinja.Jinja2Formatter.

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. Currently, the following character sets are hardcoded:

lowercase ASCII letters (a to z),
uppercase ASCII letters (A to Z) if doc-paths-lowercase is False,
digits (0 to 9),
dots (for file extensions).

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 "_".

ref-word-separator

Type:: str
Default:: '_'

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

The ref is used as the citation key when creating BibTeX format bibliographies. Therefore, characters " # ' ( ) , = { } % are not recommended for use as separators because neither bibtex nor biber can process them.

library-header-format

Type:: FormatPattern
Default:: '<ansired>{library[name]}</ansired> <ansiblue>{library[paths]}</ansiblue>'

The format of a library when shown in a picker, e.g. when using papis --pick-lib export --all. The format takes a dictionary named library with the keys name, dir, and paths.

document-field-types

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

A list of key:type strings defining expected types for document fields. 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. These values are used in the papis doctor check field-type, in the papis update command, etc.

Note: This configuration option was previously available as doctor-key-type-keys and doctor-key-type-check-keys. Both of these are deprecated (starting with Papis 0.16) and will be removed.

document-field-types-extend

Type:: List [str]
Default:: []

A list of key:type strings that extend the default ones from document-field-types. By setting these, you can extend the defaults rather than overwriting them.

Note: This configuration option was previously available as doctor-key-type-keys-extend. This version is deprecated (starting with Papis 0.16) and will be removed.

csl-style

Type:: str
Default:: 'harvard1'

The CSL style name used by the CSL exporter. For a list of styles and their naming see the Zotero Style Repository. This setting can also be a path to a local file that describes the style. User styles can be placed in the styles subfolder of the Papis configuration folder so that they are recognized just by their name.

csl-formatter

Type:: str
Default:: 'plain'

The formatter used by the CSL exporter. Currently supported formatters are “plain”, “html” and “rst”. Note that these are different to the Papis formatter and are just used to add style to the resulting citation (e.g. marking titles as italic).

exporter-csv-keys

Type:: list
Default:: []

A list of keys that should be exported to CSV. By default, this exports all the BibTeX supported keys from papis.bibtex.bibtex_keys. Note that any list keys will be concatenated using a semicolon.

exporter-csv-keys-extend

Type:: list
Default:: []

A list of keys that extend the default exporter-csv-keys. For example, the default BibTeX keys do not include the ref, so this can be added here as a simple extension.

exporter-csv-delimiter

Type:: str
Default:: ','

The delimiter used by the CSV exporter. By default this is a comma, but it can be set to other delimiters supported by the Python csv module. Setting it to a “t” (TAB) will result in a tab-separated file (TSV).

exporter-csv-dialect

Type:: str
Default:: 'excel'

The dialect used by the csv module to export the file. In general, this should not be changed unless working with a specific parser.

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 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 a different file browser, 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 --format bibtex. The intended use is to allow selecting e.g. abbreviated journal titles for publishers that require it. For example, if the document has an abbrev_journal_title key that should be used instead of the default journal key.

extra-bibtex-keys

Type:: list
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:: list
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:: list
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:: FormatPattern
Default:: '{au[family]}, {au[given]}'

A format pattern 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:: FormatPattern
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:: FormatPattern
Default:: ''

Sets 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 pattern, e.g.:

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

This setting should aim to result in unique (sub)folder names. If a (sub)folder name is not unique and the document does not appear to be a duplicate, a suffix -a, -b, etc. is added to the name. If this setting is None the pattern {doc[papis_id]} is used.

add-file-name

Type:: str
Default:: ''

Sets 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:: ''

Configures 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

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.org/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:: FormatPattern
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', 'biblatex-required-keys', 'bibtex-type', 'refs']

A list of checks that are performed by default.

doctor-default-checks-extend

Type:: List [str]
Default:: []

A list of checks that extend the default ones from doctor-default-checks. This list extends instead of overwriting the given checks.

doctor-keys-missing-keys

Type:: List [str]
Default:: ['title', 'author', 'author_list', 'ref']

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

doctor-keys-missing-keys-extend

Type:: List [str]
Default:: []

A list of keys that extend the default ones from doctor-keys-missing-keys. This list extends instead of overwriting the given keys.

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-keys-keys-extend

Type:: List [str]
Default:: []

A list of keys that extend the default ones from doctor-duplicated-keys-keys. This list extends instead of overwriting the given keys.

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-duplicated-values-keys-extend

Type:: List [str]
Default:: []

A list of keys that extend the default ones from doctor-duplicated-values-keys. This list extends instead of overwriting the given keys.

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. &.

doctor-html-codes-keys-extend

Type:: List [str]
Default:: []

A list of keys that extend the default ones from doctor-html-codes-keys. This list extends instead of overwriting the given keys.

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-html-tags-keys-extend

Type:: List [str]
Default:: []

A list of keys that extend the default ones from doctor-html-tags-keys. This list extends instead of overwriting the given keys.

doctor-field-type-separator

Type:: str
Default:: None

A separator used by the field-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:: FormatPattern
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:: FormatPattern
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

It’s possible to download papers using a proxy. We use requests to handle web queries, which has extensive documentation on how to use proxies here. The present setting sets the URL used as a proxy for 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:: List [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.

sqlite-schema-fields

Type:: List [str]
Default:: ['author', 'doi', 'journal', 'ref', 'tags', 'title', 'type', 'year', 'url']

A list with the fields that should be included in the SQLite database. In general, these are the fields that can then be searched for by name, using e.g. author:Einstein.

sqlite-schema-fields-extend

Type:: list
Default:: []

Append fields to the default sqlite-schema-fields.

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 of the status line. The format is based on 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'

The style of the margin of the selected document in the picker.

options_list.unselected_margin_style

Type:: str
Section:: tui
Default:: 'bg:ansiwhite'

The 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'

The 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'

browse_document_key

Type:: str
Section:: tui
Default:: 'c-b'

edit_notes_key

Type:: str
Section:: tui
Default:: 'c-q'

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 in the form of a 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 default Papis picker TUI, the fzf picker is generally much faster, can be configured to show helpful previews of documents, and use other fancy fzf features. However, a disadvantage is that Papis currently only supports one-line entries per document. It is also important to note that fzf will only match against what is shown on the terminal screen. In contrast, the default papis picker can match against other fields of the document, as described by the match-format setting.

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 key bindings to fzf as a Python list. Refer to the fzf documentation for more details.

fzf-header-format

Type:: FormatPattern
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. Note 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 pattern corresponding to this setting is given the additional variable c, which is the colorama library. 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 can be configured to show additional information in a preview window. 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.