Configuration file

Papis uses a configuration file in INI format. You can then have several libraries which work independently from each other.

For example, maybe you want to have one library for papers and the other for some miscellaneous documents. An example for that is given below

[papers]
dir = ~/Documents/papers

[settings]
editor = vim
default-library = papers

[books]
dir = ~/Documents/books

A more complete example of a configuration file is the following

#
# This is a general section, the settings set here will be set for
# all libraries
#
[settings]
#
# General file opener program, rifle is a nice python program
# If you're on macOS, you can write "open", if you're on linux
# you can also write "xdg-open", on windows-cygwin, you can set it to
# "cygstart"
#
opentool = rifle
# Use ranger as a file browser, a nice python program
file-browser = ranger
# Ask for confirmation when doing papis add
add-confirm = True
# Edit the info.yaml file before adding a doc into the library
# papis add --edit
add-edit = True
# Open the files before adding a document into the library
# papis add --open
add-open = True
#
# Define custom default match and header formats
#
match-format = {doc[tags]}{doc.subfolder}{doc[title]}{doc[author]}{doc[year]}
#
# Define header format with colors and multiline support
#
header-format = <red>{doc.html_escape[title]}</red>
  <span color='#ff00ff'>  {doc.html_escape[author]}</span>
  <yellow>   ({doc.html_escape[year]})</yellow>

[tui]
editmode = vi
options_list.selected_margin_style = bg:ansigreen fg:ansired
options_list.unselected_margin_style =



# Define a lib
[papers]
dir = ~/Documents/papers

# override settings from the section tui only for the papers library
# you have to 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
add-file-name = {doc[author]}{doc[title]}

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

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

# Define a lib for contacts, why not?
# To make it work you just have to define some default settings
[contacts]
dir = ~/contacts/general
database-backend = papis
mode = contact
header-format = {doc[first_name]} {doc[last_name]}
match-format = {doc[org]} {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 file can be found in the current directory of where you are issuing the papis command or in the directory of the library that you are considering in the papis command.

For instance let us 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. Then whenever you are in the ~/Documents/myproject directory papis will also source the local configuration file found there.

On the other hand, also if you have a configuration file in the library 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.

General settings

local-config-file (config-settings-local-config-file)
  • Default: .papis.config

Name AND relative path of the local configuration file that papis will additionally read if the file is present in the current directory or in the base directory of a given library.

This is useful, for instance, if you have a library somewhere for which you want special configuration settings but do not want these settings to cluster in your configuration file. It is also useful if you’re sharing a library with someone else and you want them to have the same settings in that library as you. Imagine you’re sharing a library of datasheets with your friend Fulano. You have your library at

~/Documents/lib-with-fulano

and you’ve set a local configuration file there

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

then whenever Fulano uses that library and the file is also present, his papis program will also read the configuration settings at the path above.

dir-umask (config-settings-dir-umask)
  • Default: 493

This is the default umask that will be used to create the new documents’ directories.

use-git (config-settings-use-git)
  • Default: False

Some commands will issue git commands if this option is set to True. For example in mv or rename.

browse-query-format (config-settings-browse-query-format)
  • Default: {doc[title]} {doc[author]}

The query string that is to be searched for in the browse command whenever a search engine is used.

search-engine (config-settings-search-engine)
  • Default: https://duckduckgo.com

Search engine to be used by some commands like browse.

user-agent (config-settings-user-agent)
  • Default: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_3)

User agent used by papis whenever it obtains information from external servers.

scripts-short-help-regex (config-settings-scripts-short-help-regex)
  • Default: .*papis-short-help: *(.*)

This is the format of the short help indicator in external papis commands.

info-name (config-settings-info-name)
  • Default: info.yaml

The default name of the information files.

doc-url-key-name (config-settings-doc-url-key-name)
  • Default: doc_url

Some documents might have, apart from an url, also a file url associated with them. The key name appearing in the information file is defined by this setting.

default-library (config-settings-default-library)
  • Default: papers

The name of the library that is to be searched when papis is run without library arguments.

format-doc-name (config-settings-format-doc-name)
  • 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 {doc[title]} - {doc[director]} - {doc[duration]}.

match-format (config-settings-match-format)
  • Default: {doc[tags]}{doc.subfolder}{doc[title]}{doc[author]}{doc[year]}

Default format that is used to match a document against in order to select it. For example if the match-format is equal to {doc[year]} {doc[author]} then the title of a document will not work to match a document, only the year and author.

header-format (config-settings-header-format)
  • Default:
    <ansired>{doc.html_escape[title]}</ansired>
     <ansigreen>{doc.html_escape[author]}</ansigreen>
      <blue>({doc.html_escape[year]})</blue> [<ansiyellow>{doc.html_escape[tags]}</ansiyellow>]
    

Default format that is used to show a document in order to select it.

header-format-file (config-settings-header-format-file)
  • Default: None

This option should have the path of a file with the header-format template. Sometimes templates can get big so this is a way of not cluttering the config file with text.

As an example you would set

[papers]

header-format-file = ~/.papis/config/styles/header.txt
info-allow-unicode (config-settings-info-allow-unicode)
  • Default: True

This flag is to be set if you want to allow unicode characters in your info file or not. If it is set to false then a representation for the unicode characters will be written in its place. Since we should be living in an unicode world, it is set to True by default.

Tools options

opentool (config-settings-opentool)
  • Default: xdg-open

This is the general program that will be used to open documents. As for now papis is not intended to detect the type of document to be opened and decide upon how to open the document. You should set this to the right program for the tool. If you are on linux you might want to take a look at ranger or let the default handle it in your system. For mac users you might set this to open.

browser (config-settings-browser)
  • Default: $BROWSER

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

picktool (config-settings-picktool)
  • Default: papis

This is the program used whenever papis asks you to pick a document or options in general.

Only option is:
  • papis

editor (config-settings-editor)
  • Default: $EDITOR

Editor used to edit files in papis, e.g., for the papis edit command. It defaults to the $EDITOR environment variable, if this is not set then it will default to the $VISUAL environment variable. Otherwise the default editor in your system will be used.

file-browser (config-settings-file-browser)
  • Default: xdg-open

File browser to be 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 just to name a few.

Bibtex options

bibtex-journal-key (config-settings-bibtex-journal-key)
  • Default: journal

Journal publishers may request abbreviated journal titles. This option allows the user to set the key for the journal entry when using papis export --bibtex.

Set as full_journal_title or abbrev_journal_title for whichever style required. Default is journal.

extra-bibtex-keys (config-settings-extra-bibtex-keys)
  • Default: []

When exporting documents in bibtex format, you might want to add non-standard bibtex keys such as doc_url or tags. You can add these as a valid python list of strings, for instance:

[mylib]
extra-bibtex-keys = ["tags", "doc_url"]
extra-bibtex-types (config-settings-extra-bibtex-types)
  • Default: []

Allow non-standard bibtex types to be recognized, e.g,

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

See bibtex reference.

multiple-authors-format (config-settings-multiple-authors-format)
  • Default: {au[family]}, {au[given]}

When retrieving automatic author information from services like crossref.org, papis usually builds the author field for the given document. The format how every single author name is built is given by this setting, for instance you could customize it by the following:

multiple-authors-format = {au[surname]} -- {au[given_name]}

which would given in the case of Albert Einstein the string Einstein -- Albert.

multiple-authors-separator (config-settings-multiple-authors-separator)
  • Default: `` and ``

Similarly to multiple-authors-format, this is the string that separates single authors in the author field. If it is set to `` and `` then you would have <author 1> and <author 2> and .... in the author field.

bibtex-unicode (config-settings-bibtex-unicode)
  • Default: False

Whether or not to allow direct unicode characters in the document fields to be exported into the bibtex text.

papis add options

ref-format (config-settings-ref-format)
  • Default: {doc[doi]}

This flag is set to change the ref flag in the info.yaml file when a document is imported. For example: I prefer the format FirstAuthorYear e.g. Plews2019. This would be achieved by the following:

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

The default behavior is to set the doi as the ref.

add-confirm (config-settings-add-confirm)
  • Default: False

If set to True, every time you run papis add the flag --confirm will be added automatically. If is set to True and you add it, i.e., you run papis add --confirm, then it will fave the contrary effect, i.e., it will not ask for confirmation.

add-folder-name (config-settings-add-folder-name)
  • Default: empty string

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 the papis format: {doc[author]}-{doc[title]}. Per default a hash followed by the author name is created.

add-file-name (config-settings-add-file-name)
  • Default: None

Same as add-folder-name, but for files, not folders. If it is not set, the names of the files will be cleaned and taken as-is.

add-interactive (config-settings-add-interactive)
  • Default: False

If set to True, every time you run papis add the flag --interactive will be added automatically. If is set to True and you add it, i.e., you run papis add --interactive, then it will fave the contrary effect, i.e., it will not run in interactive mode.

add-edit (config-settings-add-edit)
  • Default: False

If set to True, every time you run papis add the flag --edit will be added automatically. If it is set to True and you add something, i.e., you run papis add --edit, then it will have the contrary effect, i.e., it will not prompt to edit the info file.

add-open (config-settings-add-open)
  • Default: False

If set to True, every time you run papis add the flag --open will be added automatically. If it is set to True and you add something, i.e., you run papis add --open, then it will have the contrary effect, i.e., it will not open the attached files before adding the document to the library.

papis browse options

browse-key (config-settings-browse-key)
  • Default: url

This command provides the key that is used to generate the url. For users that run papis add --from-doi, setting browse-key to doi constructs the url from dx.doi.org/DOI, providing a much more accurate url.

Default value is set to url. If you need functionality with the search-engine option, set the option to an empty string e.g.

browse-key = ''

papis edit options

notes-name (config-settings-notes-name)
  • Default: notes.tex

In papis edit you can edit notes about the document. notes-name is the default name of the notes file, which by default is supposed to be a TeX file.

Marks

open-mark (config-settings-open-mark)
  • Default: False

If this option is set to True, every time papis opens a document it will ask to open a mark first. If it is set to False, then doing

papis open --mark

will avoid opening a mark.

mark-key-name (config-settings-mark-key-name)
  • 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 (config-settings-mark-format-name)
  • Default: mark

This is the name of the mark to be passed to the options mark-header-format etc… E.g. if you set mark-format-name = m then you could set mark-header-format = {m[value]} - {m[name]}.

mark-header-format (config-settings-mark-header-format)
  • Default: {mark[name]} - {mark[value]}

This is the format in which the mark will appear whenever the user has to pick one. You can change this in order to make marks work in the way you like. Per default it is assumed that every mark has a name and a value key.

mark-match-format (config-settings-mark-match-format)
  • Default: {mark[name]} - {mark[value]}

Format in which the mark name has to match the user input.

mark-opener-format (config-settings-mark-opener-format)
  • Default: xdg-open

Due to the difficulty to generalize opening a general document at a given bookmark, the user should set this in whichever way it 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, do

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

Downloaders

downloader-proxy (config-settings-downloader-proxy)
  • Default: None

There is the possibility of download papers using a proxy. To know more you can checkout this link.

Databases

default-query-string (config-settings-default-query-string)
  • Default: .

This is the default query that a command will take if no query string is typed in the command line. For example this is the query that is passed to the command open whenever no search string is typed:

papis open

Imagine you want to open all papers authored by John Smith whenever you do not specify an input query string, i.e., papis open. Then setting

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

would do the trick. Notice that the current example has been done assuming the database-backend = papis.

database-backend (config-settings-database-backend)
  • Default: papis

The backend to use in the database. As for now papis supports the own database system papis and whoosh.

use-cache (config-settings-use-cache)
  • Default: True

Set to False if you do not want to use the cache for the given library. This is only effective if you’re using the papis database-backend.

cache-dir (config-settings-cache-dir)
  • Default: $XDG_CACHE_HOME

whoosh-schema-fields (config-settings-whoosh-schema-fields)
  • 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 (config-settings-whoosh-schema-prototype)
  • Default:
    {
    "author": TEXT(stored=True),
    "title": TEXT(stored=True),
    "year": TEXT(stored=True),
    "tags": TEXT(stored=True),
    }
    

This is the model for the whoosh schema, check the documentation for more information.

Terminal user interface (picker)

These options are for the terminal user interface (tui). They are defined in the section tui which means that you can set them in your configuration file globally like

[tui]
status_line_format = "F1: Help"
...

or inside the library sections prepending a tui-,

[papers]
tui-status_line_format = "Library papers**
...
status_line_format (config-tui-status_line_format)
  • 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 status line. Right now there are only two variables defined:

  • selected_index

  • number_of_documents

Which are self-explanatory.

status_line_style (config-tui-status_line_style)
  • Default: bg:ansiwhite fg:ansiblack

The style the status line should have. Examples are fg:#ff00aa bg:black etc… More information can be found here .

message_toolbar_style (config-tui-message_toolbar_style)
  • Default: bg:ansiyellow fg:ansiblack

The style of the message toolbar, this toolbar is the one where messages of the echo command are rendered for instance.

options_list.selected_margin_style (config-tui-options_list.selected_margin_style)
  • Default: bg:ansiblack fg:ansigreen

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

options_list.unselected_margin_style (config-tui-options_list.unselected_margin_style)
  • Default: bg:ansiwhite

Style of the margin of the unselected documents in the picker. If you don’t want any coloring for them you can just set this setting to the empty string as such

tui-options_list.unselected_margin_style =
error_toolbar_style (config-tui-error_toolbar_style)
  • Default: bg:ansired fg:ansiblack

The style for the error messages.

editmode (config-tui-editmode)
  • Default: emacs

Whenever the user is typing text, one can use either emacs like keybindings or vi. If this does not tell you anything, you can just leave it as is.

move_down_key (config-tui-move_down_key)
  • Default: down

move_up_key (config-tui-move_up_key)
  • Default: up

move_down_while_info_window_active_key (config-tui-move_down_while_info_window_active_key)
  • Default: c-n

move_up_while_info_window_active_key (config-tui-move_up_while_info_window_active_key)
  • Default: c-p

focus_command_line_key (config-tui-focus_command_line_key)
  • Default: tab

edit_document_key (config-tui-edit_document_key)
  • Default: c-e

open_document_key (config-tui-open_document_key)
  • Default: c-o

show_help_key (config-tui-show_help_key)
  • Default: f1

show_info_key (config-tui-show_info_key)
  • Default: s-tab

go_top_key (config-tui-go_top_key)
  • Default: home

go_bottom_key (config-tui-go_bottom_key)
  • Default: end

Other

unique-document-keys (config-settings-unique-document-keys)
  • 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 some special keys, and checking if they match. Which keys are checked against is decided by this option, which should be formatted as a python list, just as in the default value.

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 (config-settings-document-description-format)
  • Default: {doc[title]} - {doc[author]}

papis sometimes will have to tell you which document it is processing through text, for instance, imagine you are updating a document

author: Albert Einstein
title: General Relativity

and papis is doing something with it. Then if your document-description-format is set to {doc[title]} - {doc[author]}, you will see that papis tells you

.....
Updating 'General Relativity - Albert Einstein'
...

so you will know exactly what is going on.