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
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:
- 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:
- Default:
493
This is the default
os.umask()
that will be used to create the new directories for documents and libraries.
- use-git
- Type:
- Default:
False
Some commands will issue git commands if this option is set to True. For example
papis mv
orpapis rename
can automatically commit any changes to a document by default. See Git support for additional details.
- user-agent
- Type:
- 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:
- 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:
- 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:
- 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:
- 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:
- Default:
'doc'
This setting controls the name of the document in the Papis format strings like in format strings such as
match-format
orheader-format
. For instance, if you are managing videos, you might want to set this option tovid
in order to set theheader-format
toheader-format = {vid[title]} - {vid[director]} - {vid[duration]}.
- match-format
- Type:
- 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 thematch-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 byheader-format
, so that any visible information can be matched.
- header-format
- Type:
- 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:
- 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 theheader-format
option will be ignored). For example, this can be set toheader-format-file = ~/.config/papis/styles/header-format.txt
- info-allow-unicode
- Type:
- 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
-
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 samedoi
, then Papis will notify you that there is already another document with thisdoi
because thedoi
key is part of theunique-document-keys
option.
- document-description-format
- Type:
- 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:
- 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:
- 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:
- Default:
'python'
Picks the formatter for templated strings in the configuration file and in various strings presented to the user. Supported formatters are
"python"
: based onpapis.format.PythonFormatter
."jinja2"
: based onpapis.format.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:
- 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:
- 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:
- 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:
- 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 neitherbibtex
norbiber
can process them.
Tools options
- opentool
- Type:
- 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 usexdg-open
. For macOS users, this should likely be set toopen
.
- browser
- Type:
- Default:
'$BROWSER'
Program to be used for opening websites, the default is the environment variable
$BROWSER
.
- picktool
- Type:
- 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"
: usespapis.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.
BibTeX options
- bibtex-journal-key
- Type:
- 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 aabbrev_journal_title
key that should be used instead of the defaultjournal
key.
- extra-bibtex-keys
- Type:
- 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 asdoc_url
ortags
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:
- 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 thenote
key.
- extra-bibtex-types
- Type:
- 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:
- 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:
- 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:
- 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 theauthor
using this setting. For instance, this can be set tomultiple-authors-format = {au[family]} -- {au[given]}
which for the author
{"family": "Einstein", "given": "Albert"}
would construct the stringEinstein -- Albert
. In most circumstances, multiple authors are then concatenated together usingmultiple-authors-separator
.
- multiple-authors-separator
- Type:
- Default:
' and '
A string used with
multiple-authors-format
to concatenate multiple authors, e.g. into theauthors
document key. By default, this is set toand
, which is the separator used by BibTeX in its so-called name-lists.
BibTeX command options
- default-read-bibfile
- Type:
- 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 usingpapis bibtex read file.bib
when used withauto-read
.
- default-save-bibfile
- Type:
- 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 usingpapis bibtex save file.bib
.
- auto-read
- Type:
- Section:
bibtex
- Default:
''
A flag used in conjunction with
default-read-bibfile
to automatically read a BibTeX file.
Add options
- ref-format
- Type:
- 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 aFirstAuthorYear
format, setref-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 usingpapis.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:
- 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 toadd-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]}``
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 isNone
the template{doc[papis_id]}
is used.
- add-file-name
- Type:
- 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:
- Default:
''
Configure a default for the
--subfolder
command-line option ofpapis add
. Note that, this setting is not allowed to contain formatting options. However, one can also specify nested sub-folders.
- add-confirm
- Type:
- Default:
False
A setting that controls the default for the
--confirm
flag ofpapis 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:
- Default:
False
A setting that controls the default for the
--edit
flag ofpapis 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:
- Default:
False
A setting that controls the default for the
--open
flag ofpapis 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:
- Default:
True
A setting that controls the default for the
--download-files
flag ofpapis 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:
- 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:
- Default:
False
A setting that controls the default for the
--auto-doctor
flag ofpapis add
andpapis 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.
Browse options
- browse-key
- Type:
- 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 ashttps://dx.doi.org/<DOI>
."isbn"
: construct a URL from the ISBN ashttps://isbnsearch/isbn/<ISBN>
."ads"
: construct a URL for the Astrophysics Data System ashttps://ui.adsabs.harvard.edu/abs/<DOI>
."auto"
: automatically pick betweenurl
,doi
andisbn
(first existing key is chosen)."search-engine"
: thesearch-engine
is used to search for the contents ofbrowse-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:
- 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 (seebrowse-key
).
Edit options
- notes-name
- Type:
- Default:
'notes.tex'
In
papis edit
you can edit notes about the document.notes-name
is the default name of the notes file. Thenotes-name
is formatted by theformatter
, so that the filename of notes can be dynamically defined, e.g.:notes-name = notes_{doc[ref]}.rst
- notes-template
- Type:
- 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 byformatter
. 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
-
A list of checks that are performed by default.
- doctor-default-checks-extend
-
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
-
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
-
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
-
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
-
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
-
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
-
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
-
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
-
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
-
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
-
A list of keys that extend the default ones from
doctor-html-tags-keys
. This list extends instead of overwriting the given keys.
- doctor-key-type-keys
- Type:
- Default:
['year:int', 'month:int', 'files:list', 'notes:str', 'author_list:list', 'doi:str', 'ref:str', 'isbn:str', 'author:str', 'journal:str', 'note:str', 'tags:list', 'type:str', 'publisher:str', 'title:str', 'shorttitle:str']
A list of strings
key:type
used by thekey-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-keys-extend
-
A list of keys that extend the default ones from
doctor-key-type-keys
. This list extends instead of overwriting the given keys.
- doctor-key-type-separator
- Type:
- Default:
None
A separator used by the
key-type
check fixer. When converting fromstr
tolist
, it is used to split the string into a list, and when converting fromlist
tostr
, 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:
- Default:
False
A setting that controls the default for the
--mark
flag ofpapis 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:
- 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 yourinfo.yaml
fileauthor: J. Krishnamurti bookmarks: - name: Chapter 1 value: 120
- mark-format-name
- Type:
- Default:
'mark'
This is the name of the mark to be passed to
mark-header-format
and other such settings, similarly toformat-doc-name
. For example, if we want to set it tom
, then other settings must be consistent, e.g.mark-format-name = m mark-header-format = {m[value]} - {m[name]}
- mark-header-format
- Type:
- 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:
- 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:
- 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:
- 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:
- 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:
- Default:
False
If True, the
time-stamp
of documents is used to create a timeline for when the documents were added.
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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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.
Citations options
You can change the name of the citation files, however we discourage this.
- citations-file-name
- Type:
- Default:
'citations.yaml'
The name of the file to store the citations of the documents.
Downloaders
Databases
- default-query-string
- Type:
- 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 defaultpapis
backend.
- database-backend
- Type:
- 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 thepickle
format as a storage format and has a query syntax based onpapis.docmatcher
."whoosh"
: a backend that uses whoosh. for its storage and querying needs.
- use-cache
- Type:
- 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:
- Default:
'$XDG_CACHE_HOME'
The default directory where the cache for the
papis
backend is stored.
- whoosh-schema-fields
- Type:
- 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 thedoi
andref
of the documents, then you could include:whoosh-schema-fields = ['doi', 'ref']
- whoosh-schema-prototype
- Type:
- 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:
- 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
andnumber_of_documents
.
- status_line_style
- Type:
- 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:
- 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:
- Section:
tui
- Default:
'bg:ansiblack fg:ansigreen'
Style of the margin of the selected document in the picker.
- options_list.unselected_margin_style
- Type:
- 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:
- 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:
- Section:
tui
- Default:
'bg:ansired fg:ansiblack'
The style for the error message toolbar.
Key bindings
For information about keybindings, see the corresponding documentation.
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-extra-flags
-
Extra flags to be passed to fzf every time it gets called.
- fzf-extra-bindings
-
Extra bindings to fzf as a Python list. Refer to the fzf documentation for more details.
- fzf-header-format
- Type:
- 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 tofzf-extra-flags
and include the colors in theheader-format
asansi
escape sequences.The Papis format string is given the additional variable
c
which contains the packagecolorama
in it. Refer to thecolorama
documentation. to see which colors are available. For instance, if you want the title in red, you would put in yourfzf-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.