Bibtex-completion, helm-bibtex, ivy-bibtex
Helm-bibtex: 
Helm-bibtex and ivy-bibtex allow you to search and manage your BibTeX bibliography. They both share the same generic backend, bibtex-completion, but one uses the Helm completion framework and the other Ivy as a front-end.
News
- 2022-01-17: More support for org-mode citations, see here. (Thanks to akirakyle.)
- 2021-08-25: It is now possible to mark and act on multiple entries in
ivy-bitex. See here. - 2021-07-25:
helm-bibtex-with-local-bibliographyandivy-bibtex-with-local-bibliographynow also use locally and globally defined bibliographies in org files. These are bibliographies specified using the new#+BIBLIOGRAPHY:key word and those in the variableorg-cite-global-bibliography. - 2021-07-18: Added a citation function for Org’s new citation system:
bibtex-completion-format-citation-org-cite(for use in configuration variablebibtex-completion-format-citation-functions) - 2021-04-12: Added a section below explaining how the bibliography can be automatically reloaded when PDFs and notes are added. See here.
- 2021-04-08: It is now possible to search for entries with PDFs and notes by entering
=has-pdf=and=has-note=. - 2020-04-29: New commands
helm-bibtex-with-notesandivy-bibtex-with-notedfor searching just within the entries that have notes. - 2018-06-09: Added virtual APA field
author-or-editorfor use in notes templates. - 2018-06-02: Reload bibliography proactively when bib files are changed.
- 2017-10-21: Added support for multiple PDFs or other file types. See sections “Additional PDFs” and “Other file types than PDF”.
- 2017-10-10: Added support for
@stringconstants. - 2017-10-02: Use date field if year is not defined.
- 2017-09-29: If there is a BibTeX entry, citation macro, or org-bibtex entry at point, the corresponding publication will be pre-selected in helm-bibtex and ivy-bibtex giving quick access to PDFs and other functions.
See NEWS.org for old news.
Key features
- Quick access to your bibliography from within Emacs
- Powerful search capabilities
- Provides instant search results as you type
- Tightly integrated with LaTeX authoring, emails, Org mode, etc.
- Open the PDFs, URLs, or DOIs associated with an entry
- Insert LaTeX cite commands, Ebib links, or Pandoc citations, BibTeX entries, or plain text references at point, attach PDFs to emails
- Support for note taking
- Quick access to online bibliographic databases such as Pubmed, arXiv, Google Scholar, Library of Congress, etc.
- Import BibTeX entries from CrossRef and other sources.
Helm-bibtex’ and ivy-bibtex’ main selling points are efficient search in large bibliographies using powerful search expressions and tight integration into your Emacs workflows. They both can perform the following actions on entries matching the search expression: open the PDF associated with an entry, its URL or DOI, insert a citation for that entry, the BibTeX key, the BibTeX entry, or a plain text reference, attach the PDF to an email, take notes, edit the BibTeX entry. Many aspects can be configured to suit personal preferences.
Example
Below is a screenshot showing a helm-bibtex search for entries containing the expression “eye tracking”.
The regular expression eye.?tracking allows searching for different spellings (“eye tracking”, “eye-tracking”, “eyetracking”). A looped square symbol (⌘) next to an entry indicates that a PDF is available. A pen symbol (✎) means that there are notes attached to this entry. At the bottom, there are entries that can be used to search in online databases.
Installation
The easiest way to install helm-bibtex or ivy-bibtex is through MELPA. Alternatively, put the files bibtex-completion.el and either helm-bibtex.el or ivy-bibtex.el in a directory included in your load-path and add the following line to your start-up file (typically init.el):
(autoload 'helm-bibtex "helm-bibtex" "" t)or
(autoload 'ivy-bibtex "ivy-bibtex" "" t)
;; ivy-bibtex requires ivy's `ivy--regex-ignore-order` regex builder, which
;; ignores the order of regexp tokens when searching for matching candidates.
;; Add something like this to your init file:
(setq ivy-re-builders-alist
'((ivy-bibtex . ivy--regex-ignore-order)
(t . ivy--regex-plus)))Helm-bibtex and ivy-bibtex depend on a number of packages that will be automatically installed if you use MELPA.
When using helm-bibtex or ivy-bibtex, make sure that helm or ivy is correctly configured (see helm documentation or ivy documentation).
Minimal configuration
A minimal configuration involves telling bibtex-completion where your bibliographies can be found:
(setq bibtex-completion-bibliography
'("/path/to/bibtex-file-1.bib"
"/path/to/bibtex-file-2.bib"))Org-bibtex users can also specify org-mode bibliography files, in which case it will be assumed that a BibTeX file exists with the same name and extension bib instead of org. If the bib file has a different name, use a cons cell ("orgfile.org" . “bibfile.bib") instead:
(setq bibtex-completion-bibliography
'("/path/to/bibtex-file-1.bib"
"/path/to/org-bibtex-file.org"
("/path/to/org-bibtex-file2.org" . "/path/to/bibtex-file.bib")))Basic configuration (recommended)
PDF files
Specify where PDFs can be found:
(setq bibtex-completion-library-path '("/path1/to/pdfs" "/path2/to/pdfs"))Bibtex-completion assumes that the name of a PDF consists of the BibTeX key followed plus a user-defined suffix (.pdf by default). For example, if a BibTeX entry has the key Darwin1859, bibtex-completion searches for Darwin1859.pdf.
If the BibTeX entries have a field that specifies the full path to the PDFs, that field can also be used. For example, JabRef and Zotero store the location of PDFs in a field called File:
(setq bibtex-completion-pdf-field "File")If bibtex-completion-pdf-field is non-nil, bibtex-completion will first try to retrieve the file specified in this field. If the field is not set for an entry or if the specified file does not exists, bibtex-completion falls back to the method described above (searching for key + .pdf in the directories listed in bibtex-completion-library-path).
File specifications can be bare paths or follow the format used by JabRef, Zotero, Calibre, and Mendeley. This format also allows the specification of multiple files (e.g., the main paper and supplementary material). Examples:
File = {/path/to/article.pdf}File = {:/path/to/article.pdf:PDF}File = {:/path/to/article.pdf:PDF;:/path/to/supplementary_materials.pdf:PDF}
Notes
Bibtex-completion supports two methods for storing notes. It can either store all notes in one file or store notes in multiple files, one file per publication. In the first case, the customization variable bibtex-completion-notes-path has to be set to the full path of the notes file:
(setq bibtex-completion-notes-path "/path/to/notes.org")If one file per publication is preferred, bibtex-completion-notes-path should point to the directory used for storing the notes files:
(setq bibtex-completion-notes-path "/path/to/notes")The names of these files consist of the BibTeX key plus a user-defined suffix (.org by default).
At this point most people will be ready to go. Skip to Usage below to see how to use helm-bibtex and ivy-bibtex.
Follow processor for helm
Invoking helm-bibtex or ivy-bibtex when point is on an org-mode citation will automatically select that key. However, the default org-open-at-point on a org citation will take you to the corresponding bibliography entry. The following code will change this behavior to instead open helm-bibtex-follow when following an org citation by entering RET or clicking on it:
(setq org-cite-follow-processor 'helm-bibtex-org-cite-follow)Note in the case of an org citation with multiple keys, the above code will not preselect any entry when the [cite: portion is selected. See here for the ivy alternative.
Advanced configuration
Customize layout of search results
The variable bibtex-completion-display-formats can be used to customize how search results are presented on a per-entry-type basis. The default is
'((t . "${author:36} ${title:*} ${year:4} ${=has-pdf=:1}${=has-note=:1} ${=type=:7}"))which means that all entry types are presented in the same way: authors, title, year, … In this format string, the numbers indicate how much space is reserved for the respective field. If there is a * instead of a number that means that this field gets whatever space remains. Here is a setup that uses a different layout for different entry types:
(setq bibtex-completion-display-formats
'((article . "${=has-pdf=:1}${=has-note=:1} ${=type=:3} ${year:4} ${author:36} ${title:*} ${journal:40}")
(inbook . "${=has-pdf=:1}${=has-note=:1} ${=type=:3} ${year:4} ${author:36} ${title:*} Chapter ${chapter:32}")
(incollection . "${=has-pdf=:1}${=has-note=:1} ${=type=:3} ${year:4} ${author:36} ${title:*} ${booktitle:40}")
(inproceedings . "${=has-pdf=:1}${=has-note=:1} ${=type=:3} ${year:4} ${author:36} ${title:*} ${booktitle:40}")
(t . "${=has-pdf=:1}${=has-note=:1} ${=type=:3} ${year:4} ${author:36} ${title:*}")))For this to work, you have to add journal and booktitle to bibtex-completion-additional-search-fields. See next section.
Fields used for searching
The default fields used for searching are: author, title, year, BibTeX key, entry type (article, inproceedings, …). The variable bibtex-completion-addition-search-fields can be used to extend this list. Example:
(setq bibtex-completion-additional-search-fields '(keywords))Symbols used for indicating the availability of notes and PDF files
(setq bibtex-completion-pdf-symbol "⌘")
(setq bibtex-completion-notes-symbol "✎")Different naming schemes for PDF files
If the PDFs files follow a different naming scheme than BibTeX key + .pdf, the function bibtex-completion-find-pdf-in-library can be modified to accommodate that.
Application used for opening PDFs
By default Emacs is used to open PDF files. This means that either DocView is used, or, if installed, the much superior pdf-tools extension which offers features such as incremental search in PDF files and creation and modification of annotations that are compatible with annotations created by Adobe software.
To configure another PDF viewer the customization variable bibtex-completion-pdf-open-function can be used. Here is an example configuration for the OS X PDF viewer Skim:
(setq bibtex-completion-pdf-open-function
(lambda (fpath)
(call-process "open" nil 0 nil "-a" "/Applications/Skim.app" fpath)))Here is another example for the Linux PDF viewer Evince:
(setq bibtex-completion-pdf-open-function
(lambda (fpath)
(call-process "evince" nil 0 nil fpath)))It is sometimes desirable to have both options (Emacs itself and external viewer) to open the PDF. The following adds an action with Evince as an external viewer bound to P, in addition to the regular Emacs viewer with p. The action works with ivy-bibtex; it would have to be adjusted for helm-bibtex (change the path to another viewer if necessary):
(defun bibtex-completion-open-pdf-external (keys &optional fallback-action)
(let ((bibtex-completion-pdf-open-function
(lambda (fpath) (start-process "evince" "*helm-bibtex-evince*" "/usr/bin/evince" fpath))))
(bibtex-completion-open-pdf keys fallback-action)))
(ivy-bibtex-ivify-action bibtex-completion-open-pdf-external ivy-bibtex-open-pdf-external)
(ivy-add-actions
'ivy-bibtex
'(("P" ivy-bibtex-open-pdf-external "Open PDF file in external viewer (if present)")))Additional PDFs
You may store additional PDFs for a given entry, such as an annotated version of the original PDF, a file containing supplemental material, or chapter files. If the file field is used to link PDFs to entries (see section PDF files), these additional PDFs can simply be added to that field. If the action “Open PDF file” is triggered, you will then be prompted for the file to open.
If the file field is not used but instead the naming scheme bibtex-key + .pdf (again see PDF files), you can obtain the same behavior with:
(setq bibtex-completion-find-additional-pdfs t)All files whose name start with the BibTeX key will then be associated with an entry. It is then sufficient to name your files accordingly (for example with the rename utility). Examples:
bibtex-key-annotated.pdfbibtex-key-supplemental.pdfbibtex-key-chapter1.pdf
Note that for performance reasons, these additional files are only detected when triggering an action, such as “Open PDF file”. When the whole bibliography is loaded, only the “main” PDF bibtex-key.pdf is detected.
Other file types than PDF
If documents are referenced via the naming scheme bibtex-key.pdf but you are storing files in a different format than PDF, you can set the variable bibtex-completion-pdf-extension accordingly. Example:
(setq bibtex-completion-pdf-extension ".djvu")If you store files in various formats, then you can specify a list instead of a single file type:
(setq bibtex-completion-pdf-extension '(".pdf" ".djvu", ".jpg"))Extensions in this list are then tried sequentially until a file is found. Beware that this can reduce performance for large bibliographies.
Browser used for opening URLs and DOIs
By default bibtex-completion uses whatever is Emacs’ default. However, there are a variety of alternatives (see the documentation of bibtex-completion-browser-function for a complete list). Example:
(setq bibtex-completion-browser-function 'browser-url-chromium)User-defined functions can be used, too:
(setq bibtex-completion-browser-function
(lambda (url _) (start-process "firefox" "*firefox*" "firefox" url)))Format of citations
Bibtex-completion creates citations based on the major mode in which the citation is inserted:
- org-mode
- insert link for opening the entry in Ebib
- latex-mode
- insert LaTeX citation command
- markdown-mode
- insert Pandoc citation macro
- python-mode
- insert sphinxcontrib-bibtex citation role
- rst-mode
- insert sphinxcontrib-bibtex citation role
- other modes
- insert plain BibTeX key
The list of modes can be extended and the citation functions can be changed using the customization variable bibtex-completion-format-citation-functions. For example, people who don’t use Ebib might prefer links to the PDFs instead of Ebib-links in org mode files:
(setq bibtex-completion-format-citation-functions
'((org-mode . bibtex-completion-format-citation-org-link-to-PDF)
(latex-mode . bibtex-completion-format-citation-cite)
(markdown-mode . bibtex-completion-format-citation-pandoc-citeproc)
(default . bibtex-completion-format-citation-default)))When you want to create a reading to-do list in org-mode, you may perfer using the title of the PDF file in the link. To achieve this goal, you can modify the variable bibtex-completion-format-citation-functions using the following code snippet:
(setq bibtex-completion-format-citation-functions
'((org-mode . bibtex-completion-format-citation-org-title-link-to-PDF)
(latex-mode . bibtex-completion-format-citation-cite)
(markdown-mode . bibtex-completion-format-citation-pandoc-citeproc)
(default . bibtex-completion-format-citation-default)))A citation function has to accept a list of keys as input and return a string containing the citations. See the predefined citation functions for examples.
LaTeX citation commands
Bibtex-completion prompts for a LaTeX citation command when inserting citations in LaTeX documents. The list of commands available for auto-completion can be defined using the variable bibtex-completion-cite-commands.
The default setting includes all cite commands defined in biblatex (except multicite commands and \volcite et al.). If no command is entered, a default command is used which can be configured using bibtex-completion-cite-default-command. The default value for the default command is cite. The variable bibtex-completion-cite-default-as-initial-input controls how the default command is used. If t, it is inserted into the minibuffer before reading input from the user. If nil, it is not inserted into the minibuffer but used as the default if the user doesn’t enter anything.
By default, bibtex-completion also prompts for the optional pre- and postnotes for the citation. This can be switched off by setting the variable bibtex-completion-cite-prompt-for-optional-arguments to nil.
See also the section Insert LaTeX cite commands below.
Online databases
Online databases can be configured using the customization variable bibtex-completion-fallback-options. This variable contains an alist where the first element of each entry is the name of the database and the second element is either a URL or a function. The URL must contain a %s at the position where the current search expression should be inserted. If a function is used, that function should take this search expression as single argument.
Key-bindings
For quick access to the bibliography, bind the search command, helm-bibtex or ivy-bibtex, to a convenient key.
Helm-bibtex: I use the menu key as the prefix key for all helm commands and bind helm-bibtex to b. Helm-bibtex can then be started using <menu> b. It is also useful to bind helm-resume to <menu> in helm-command-map. With this binding, <menu> <menu> can be used to reopen the last helm search.
(global-set-key (kbd "<menu>") 'helm-command-prefix)
(define-key helm-command-map "b" 'helm-bibtex)
(define-key helm-command-map "B" 'helm-bibtex-with-local-bibliography)
(define-key helm-command-map "n" 'helm-bibtex-with-notes)
(define-key helm-command-map (kbd "<menu>") 'helm-resume)Ivy-bibtex: You could similarly bind ivy-bibtex to <menu> b and ivy-resume to <menu> <menu>.
Predefined searches
For convenience, frequent searches can be captured in commands and bound to key combinations. Below is example code that defines a search for publications authored by “Jane Doe” and binds the search command to C-x p.
Helm-bibtex:
(defun helm-bibtex-my-publications (&optional arg)
"Search BibTeX entries authored by “Jane Doe”.
With a prefix ARG, the cache is invalidated and the bibliography reread."
(interactive "P")
(helm-bibtex arg nil "Jane Doe"))
;; Bind this search function to Ctrl-x p:
(global-set-key (kbd "C-x p") 'helm-bibtex-my-publications)Ivy-bibtex:
(defun ivy-bibtex-my-publications (&optional arg)
"Search BibTeX entries authored by “Jane Doe”.
With a prefix ARG, the cache is invalidated and the bibliography reread."
(interactive "P")
(when arg
(bibtex-completion-clear-cache))
(bibtex-completion-init)
(ivy-read "BibTeX Items: "
(bibtex-completion-candidates)
:initial-input "Jane Doe"
:caller 'ivy-bibtex
:action ivy-bibtex-default-action))
;; Bind this search function to Ctrl-x p:
(global-set-key (kbd "C-x p") 'ivy-bibtex-my-publications)Change the available actions
Pressing <enter> on a publication triggers the “default action” which is opening the PDF associated with the publication, if present, or its URL or DOI otherwise. Pressing <tab> in helm-bibtex or M-o in ivy-bibtex instead displays an action menu listing the available actions. Here is the list of all available actions along with their functions (these are the generic action functions, for helm-bibtex the function names start with helm-bibtex- instead of bibtex-completion-, and for ivy-bibtex they start with ivy-bibtex- instead):
- Open PDF, URL or DOI:
bibtex-completion-open-any - Open PDF file (if present):
bibtex-completion-open-pdf - Open URL or DOI in browser:
bibtex-completion-open-url-or-doi - Insert citation:
bibtex-completion-insert-citation - Insert reference:
bibtex-completion-insert-reference - Insert BibTeX key:
bibtex-completion-insert-key - Insert BibTeX entry:
bibtex-completion-insert-bibtex - Attach PDF to email:
bibtex-completion-add-PDF-attachment - Edit notes:
bibtex-completion-edit-notes - Show entry:
bibtex-completion-show-entry - Add PDF to library:
bibtex-completion-add-pdf-to-library
Helm-bibtex: The action list can be modified through the commands helm-add-action-to-source and helm-delete-action-from-source. For instance, the following adds a new action helm-bibtex-open-annotated-pdf (see above) just after the first item in the list above:
(helm-add-action-to-source
"Open annotated PDF (if present)" 'helm-bibtex-open-annotated-pdf
helm-source-bibtex 1)If the last, numerical argument in helm-add-action-to-source is omitted, the new action is added at the end of the list. Since the default action is simply the first entry in the list of actions, the default action can be changed by deleting an action and re-inserting it at the top of the list. Below is an example showing how to make “Insert BibTeX key” the default action:
(helm-delete-action-from-source "Insert BibTeX key" helm-source-bibtex)
(helm-add-action-to-source "Insert BibTeX key" 'helm-bibtex-insert-key helm-source-bibtex 0)Ivy-bibtex: The default action and the additional available actions are set separately. The default action is controlled by the variables ivy-bibtex-default-action and ivy-bibtex-default-multi-action, with the latter intended for lists of marked entries (see Apply actions to multiple entries). For example, the following code changes the default action to “insert BibTeX key”:
(setq ivy-bibtex-default-action 'ivy-bibtex-insert-key)In the same way, the following code sets the default action for lists of marked entries to “insert BibTeX key” which will insert a nice comma-separated list of keys:
(setq ivy-bibtex-default-multi-action 'ivy-bibtex-insert-key)The additional actions are set by passing the desired action list to the command ivy-set-actions. For instance, the following codes keeps only two available actions in addition to the default one:
(ivy-set-actions
'ivy-bibtex
'(("p" ivy-bibtex-open-any "Open PDF, URL, or DOI" ivy-bibtex-open-any)
("e" ivy-bibtex-edit-notes "Edit notes" ivy-bibtex-edit-notes)))The letters p and e are the key bindings for the two actions in the action menu. The key binding o is reserved for the default action. The second appearance of the action in this code alerts ivy that the action can handle lists of marked entries. It can safely be omitted if the right thing to do is simply apply the action to each entry in turn.
If you only want to add new actions at the end of the action list, you can alternatively use the command ivy-add-actions. For instance, the following adds a new action ivy-bibtex-open-annotated-pdf (see above) at the end of the action list:
(ivy-add-actions
'ivy-bibtex
'(("P" ivy-bibtex-open-annotated-pdf "Open annotated PDF (if present)" ivy-bibtex-open-annotated-pdf)))Create new actions
Creating a new action for helm-bibtex or ivy-bibtex can be done in three steps. For an example see Action for opening annotated PDFs above.
The first and main step is to create a generic action function bibtex-completion-<action> (e.g. bibtex-completion-open-annotated-pdf). This function should take as single argument a list of BibTeX keys and perform the action on the corresponding BibTeX entries.
The second step is to tailor the generic action function for helm-bibtex or ivy-bibtex, so that it will be run in the correct buffer and receive the keys of the selected entries).
Helm-bibtex: This is simply done with:
(helm-bibtex-helmify-action bibtex-completion-<action> helm-bibtex-<action>)Ivy-bibtex: This is simply done with:
(ivy-bibtex-ivify-action bibtex-completion-<action> ivy-bibtex-<action>)The third and final step is to make the tailored action function helm-bibtex-<action> or ivy-bibtex-<action> available in helm-bibtex or ivy-bibtex by adding it to the action menu. See Change the available actions.
Window size
Helm-bibtex: By default helm-bibtex uses the entire frame to display the bibliography. This can be changed by setting the variable helm-bibtex-full-frame to nil, in which case helm’s standard is used (typically vertical split, with the helm search being shown in the lower window).
Ivy-bibtex: Ivy-bibtex always displays the bibliography in the minibuffer. The variable ivy-height controls the number of lines for the minibuffer window in all ivy commands.
Templates for new notes
Bibtex-completion populates new notes with some basic information about the publication. In the case of just one note file for all publications, new entries look like the following example:
Gigerenzer, G. (1998): We need statistical thinking, not statistical rituals :PROPERTIES: :Custom_ID: Gigerenzer1998 :END:
The title of the new section consists of the author names, the year, and the title of the publication. The property Custom_ID specifies the BibTeX key of the entry (it’s named Custom_ID for compatibility with org-ref).
In the case of one file per publication, a new notes file contains a title in the following format:
#+TITLE: Notes on: Gigerenzer, G. (1998): We need statistical thinking, not statistical rituals
If other formats are desired, the templates for new notes can be changed using the customization variables bibtex-completion-notes-template-one-file and bibtex-completion-notes-template-multiple-files.
File type of note files
By default bibtex-completion assumes that note files are in org-mode format. However, any other format can be used as well. In the case of just one notes file, it is enough to set bibtex-completion-notes-path to point to the desired file. In the case of multiple note files, the type of the files can be specified using the customization variable bibtex-completion-notes-extension. For example, if Markdown is the desired file type:
(setq bibtex-completion-notes-path "/path/to/notes")
(setq bibtex-completion-notes-extension ".md")If the file type is set to something else than org-mode, the templates for new note files need to be adjusted as well. See the section above for details.
Refresh bibliography when new PDFs and notes are added
Bibtex-completion automatically reloads the bibliography when a .bib file is changed on disk. However, bibtex-completion does not watch PDFs and notes. Thus, when a new PDF or note is added, the bibliography must be manually reloaded to display the PDF and note symbols correctly (via prefix argument, e.g. C-u M-x helm-bibtex). Unfortunately, implementing automatic reloading for PDFs and notes is not entirely straightforward since bibtex completion is quite flexible in how PDFs and notes can be handled. But for simple setups, there is an easy solution: just watch the bibtex-completion-library-path and bibtex-completion-notes-path directories and reload the bibliography when they change. Example for the PDF directory:
(setq tmalsburg-pdf-watch
(file-notify-add-watch bibtex-completion-library-path
'(change)
(lambda (event) (bibtex-completion-candidates))))Usage
Search publications
Use M-x helm-bibtex or M-x ivy-bibtex to start a new search. The default fields for searching are: author, title, year, BibTeX key, and entry type. Regular expressions can be used. Example searches:
Everything published by Janet Fodor:
janet fodor
All PhD theses:
phdthesis
Lyn Frazier’s PhD thesis:
phdthesis frazier
Publications about eye tracking. A regular expression is used to match various spellings (“eyetracking”, “eye tracking”, “eye-tracking”):
eye.?tracking
Conference presentations in 2013:
2013 inproceedings
Publications from 2010 and 2011:
\(2010\|2011\)
Articles co-authored by David Caplan and Gloria Waters:
article waters caplan
Search for articles by David Caplan that are not co-authored by Gloria Waters:
article caplan !waters
Search in the local bibliography
Use helm-bibtex-with-local-bibliography or ivy-bibtex-with-local-bibliography to start a search in the current buffer’s “local bibliography”, instead of the “global bibliography” defined by bibtex-completion-bibliography. If the current file is a BibTeX file, that bibliography is going to be used. If the current file is a LaTeX file, reftex will be used to determine the local bibliography from the standard LaTeX bibliography commands \bibliography and \addbibresource. If the file is an org file, the local and/or global org bibliography is used (as specified using the new #+BIBLIOGRAPHY: key word and the variable org-cite-global-bibliography). If no local bibliography can be found, the global bibliography (bibtex-completion-bibliography) will be used.
Search in entries with notes
Use helm-bibtex-with-notes or ivy-bibtex-with-notes to search only among entries that have notes. Particularly useful in combination with ~org-roam-bibtex.el~.
Search the word under the cursor
A common use case is where a search term is written in a document (say in your LaTeX manuscript) and you want to search for it in your bibliography. In this situation, just start helm-bibtex or ivy-bibtex and enter M-n. This inserts the word under the cursor as the search term. (This is a helm / ivy feature and can be used in all helm / ivy commands, not just helm-bibtex / ivy-bibtex.) Note that it is also possible to use BibTeX keys for searching. So if your cursor is on a BibTeX key (e.g., in a LaTeX cite command) you can start helm-bibtex or ivy-bibtex, hit M-n and see the entry associated with that BibTeX key. Special case: you want to open the PDF associated with the BibTeX key under the cursor: M-x helm-bibtex M-n RET or M-x ivy-bibtex M-n RET. This is of course shorter if you bind helm-bibtex or ivy-bibtex to a convenient key (see Key-bindings).
Actions for selected publications
The available actions are:
- Open a PDF if present, or a URL or DOI (default action)
- Open the URL or DOI in browser
- Insert citation
- Insert reference
- Insert BibTeX key
- Insert BibTeX entry
- Attach PDF to email
- Edit notes
- Show entry
- Add PDF to library
Helm-bibtex: Select an entry and press <return> to execute the default action. Alternatively, press TAB (tabulator) to see a list of all available actions, execute one of them and exit helm-bibtex.
Ivy-bibtex: Select an entry and press <return> to execute the default action. Alternatively, press M-o to see a list of all available actions, execute one of them and exit ivy-bibtex.
Apply actions to multiple entries
Helm-bibtex: Start helm-bibtex, enter the search expression, move the cursor to the matching entry and enter C-<space> (control + space bar) to mark this entry, optionally change your search expression, mark more entries, finally press <return> or <tab> to execute an action for all selected entries at once and exit helm-bibtex.
Ivy-bibtex: Start ivy-bibtex, enter the search expression, move the cursor to the matching entry and enter C-<space> (control + space bar) to mark this entry, optionally change your search expression, mark more entries, finally press <return> to execute the default action on all the selected entries or M-o to choose another action. Press S-<space> (shift + space bar) to un-mark a marked entry.
A colleague asks for copies of your new papers
Helm-bibtex: Start an email to your colleague (C-x m) and execute helm-bibtex. Search for your new publications and mark them with C-<space>, then press <f7> to execute the action “Attach PDF to email”. Then M-x helm-resume (the publications are still marked) and press <f6> to execute the action “Insert BibTeX entry”. Optionally insert more human readable references using M-x helm-resume and <f4> to execute the action “Insert reference”. Send email (C-c C-c). Done. This takes less than 10 seconds.
Ivy-bibtex: Start an email to your colleague (C-x m) and execute ivy-bibtex. Search for your new publications and and mark them with C-<space>, then press C-M-o a to execute the action “Attach PDF to email” while keeping ivy open. Then press M-o b to execute the action “Insert BibTeX entry” or insert more human readable references using M-o r to execute the action “Insert reference”. Send email (C-c C-c). Done. This takes less than 10 seconds.
Of course, this assumes that you’re sending email from Emacs, e.g. via Mu4e.
Tag publications
Helm-bibtex and ivy-bibtex have powerful search capabilities but some common searches cannot be performed simply because the relevant information is typically not represented in BibTeX files. For example, bibtex-completion doesn’t know whether a conference presentation was a talk or a poster because both are represented as inproceedings. So if you want to compile a list of your conference talks (e.g., for your CV), that’s not possible – not without some additional work. One solution is to “tag” publications. Tags are like keywords except that they don’t represent the content of a publications but meta data. Example:
@inproceedings{BibtexKey2015,
author = {Jane Doe and Monika Mustermann},
title = {This is the title},
crossref = {XYZ-conference-2015},
keywords = {keyword1, keyword2},
pages = {10},
tags = {poster},
}Since tags is not a standard BibTeX field, bibtex-completion by default doesn’t consider it when searching. In order to be able to search for tags, we therefore have to tell bibtex-completion that the tags field is relevant, too:
(setq bibtex-completion-additional-search-fields '(tags))
There are many other ways in which tags can be used. For example, they can be used to mark articles that you plan to read or important articles or manuscripts in progress, etc. Be creative.
Insert LaTeX cite commands
The action for inserting a citation command into a LaTeX document prompts for the citation command and, if applicable, for the pre- and postnote arguments. The prompt for the citation command has its own minibuffer history, which means that previous inputs can be accessed by pressing the <up> key for helm-bibtex or M-p for ivy-bibtex. By pressing <down> it is also possible to access the list of all citation commands defined in biblatex (except for multicite commands and volcite et al. which have different argument structures). The prompt also supports auto-completion via the tab key. If no command is entered, the default command is used. The default command is defined in the customization variable bibtex-completion-cite-default-command. By default, helm-bibtex and ivy-bibtex prompt for pre- and postnotes for the citation. This can be switched off by setting the variable bibtex-completion-cite-prompt-for-optional-arguments to nil.
Force reloading of the bibliography
Bibtex-completion caches the bibliography to prevent a costly reread when a new query is started. However, bibtex-completion does not check whether new PDFs or notes were added since the last read and hence the symbols indicating the presence or absence of these items may be incorrect. A reread can be forced using a prefix argument.
Helm-bibtex: Either do C-u M-x helm-bibtex or C-u followed by whatever key binding you use to invoke helm-bibtex.
Ivy-bibtex: Either do C-u M-x ivy-bibtex or C-u followed by whatever key binding you use to invoke ivy-bibtex.
Import BibTeX from CrossRef
Helm-bibtex: Start helm-bibtex and enter search terms. Then select “CrossRef” in the section titled “Fallback options”. (You can use the left and right arrow keys to switch between sections.)
Ivy-bibtex: Start ivy-bibtex and enter search terms. Then press M-o f to see the list of fallback options and select “CrossRef”.
This will use biblio.el to search the CrossRef database. In the results list, place the cursor on the entry of interest and hit c to copy the BibTeX for that entry or i to insert it at point. Press q to close the buffer with the search results. See the documentation of biblio.el for details.
Searching on a different source
Sometimes the search term will not yield the desired results on the first fallback source selected and you may wish to pick another fallback option with the same search term.
For this you can use helm-resume (or ivy-resume) to get back to the initial helm (ivy) menu with the last search term pre-entered allowing you to efficiently choose another option.
Advanced usage (a.k.a. hacks)
Below I provide code that was useful for me or other users. Note that this code may make assumptions that do not hold in your setup. Read the code carefully before executing it and make changes as needed.
Convert multiple note files to one notes file
The code below reads all note files in your bibtex-completion-notes-path and creates a new notes file containing a section for each publication. This code assumes that bibtex-completion is still configured for multiple note files and that you want to store the notes in the file notes.org in your bibtex-completion-notes-path. The code also adds a level to all org headlines found in the individual note files (because top-level headings are used for the publications in the new notes file). If a note file doesn’t have a corresponding entry in the bibliography, it is ignored.
(let ((note-files (directory-files bibtex-completion-notes-path t "^[^.]+\\.org$"))
(bibtex-completion-notes-path (f-join bibtex-completion-notes-path "notes.org")))
(cl-loop
for note-file in note-files
for key = (f-no-ext (f-filename note-file))
do (condition-case nil
(progn
(bibtex-completion-edit-notes key)
(insert (with-temp-buffer
(insert-file-contents note-file)
(replace-regexp "^*" "**")
(buffer-string))))
(error nil))))Create a BibTeX file containing only specific entries
Say you want to create a BibTeX file containing only entries that you cited in an article, then you can use the following code to populate the new BibTeX file with entries:
(progn
(switch-to-buffer (generate-new-buffer "my_new_bibliography.bib"))
(--map (insert (bibtex-completion-make-bibtex it)) (-distinct '("Key1" "Key2"))))If LaTeX is used to write the article, grep and sed can be used to extract the cited keys:
grep '\entry{' manuscript.bbl | sed 's/^.*\entry{\([^}]*\)}.*$/\1/'Create a list with the paths of all PDFs in your bibliography
This can be useful if you’d like to transfer all your PDFs to another directory or similar.
(flatten-tree
(mapcar
(lambda (entry) (bibtex-completion-find-pdf entry))
(bibtex-completion-candidates)))Reverse order of entries
Helm-bibtex and ivy-bibtex display entries in the order in which they appear in the BibTeX file reversed. This way, entries that were added at the bottom of the BibTeX file show up at the top when searching. There is currently no support for sorting but if you want to reverse the order of entries you can use the code below:
(advice-add 'bibtex-completion-candidates
:filter-return 'reverse)Use ivy-bibtex as an org-cite-follow-processor
As mentioned here, the default org-open-at-point on a org citation will take you to the corresponding bibliography entry. The following code will change this behavior to instead open ivy-bibtex when following an org citation by entering RET or clicking on it:
(org-cite-register-processor 'my-ivy-bibtex-org-cite-follow
:follow (lambda (_ _) (ivy-bibtex)))
(setq org-cite-follow-processor 'my-ivy-bibtex-org-cite-follow)Troubleshooting
Helm-bibtex doesn’t show any entries
This usually happens when a BibTeX file isn’t well-formed. Common problems are opening quotes or parentheses that don’t have matching counterparts. Unfortunately, Helm swallows the error message that is generated in these cases and just shows an empty buffer.
One way to diagnose the problem is to call the function for reading BibTeX directly and to see what error message it produces:
(bibtex-completion-candidates)If you see
forward-sexp: Scan error: "Unbalanced parentheses", 181009, 512282
this means that there is an unmatched opening parenthesis at the position 181009. To find this parenthesis, open the BibTeX file and do M-: (goto-char 181009) RET. You can also use the command M-x bibtex-validate RET to check for errors. Fix any problems and try again.