Literature is the lifeblood of intellectuals and researchers alike. Note-taking systems are, therefore, often connected to a bibliographic database (such as a BibTeX file). These databases help you to create and find notes related to books, articles and other reference types. Bibliographic databases are also helpful because they provide access to related materials, such as links to online sources and stored electronic versions of relevant books or articles. Lastly, bibliographies are necessary to add citations to your writings.
The Citar-Denote auxiliary package integrates the Citar bibliography package with the Denote note-taking system.
Citar-Denote provides a global minor mode that enables linking notes to a bibliographic entry. Each bibliography item can have one or more notes, and each note can relate to one or more pieces of literature. The reference line in the front matter of your notes contains the citation keys (separated by a semicolon), and each bibliographic note is marked with the _bib file tag.
In the context of this package, a reference contains one or more pieces of literature associated with a Denote file. A citation is an inline citation reference used for bibliographies. References are for literature reviews; citations are primarily used in other note types.
The Citar-Denote package works with all Denote file types (Org Mode, Markdown (YAML and TOML) and plain text). The package also supports BibTeX, BibLaTeX and CSL bibliography formats.
- Bibliographic entry: An item in the bibliography (book, article, chapter etc.) accessed via the Citar completion menu.
- Bibliographic note: A Denote file linked to one or more bibliographic entries.
- Reference: Link in a bibliographic note to a bibliographic entry (the reference line).
- Citation: A citation of a bibliographic entry in a note. Citations can occur in regular notes and in bibliographic notes.
- Citation key: The unique key used to identify a bibliographic entry
Several Emacs packages are available that can link bibliography files to notes. The Ebib, Helm-BibTeX and Ivy-BibTeX each use their own completion system. The Citar package uses minibuffer completion and integrates perfectly with the popular Vertico - Marginalia - Consult - Embark toolchain. The Citar package is an ideal companion to Denote due to its extensibility and use of the minibuffer.
The most common behaviour for these bibliography managers is that the filename for the relevant note includes the citation key (e.g. einstein_1905.org) so it can be linked to the BibTeX entry. Other systems, such as Org Roam, use a database to store these relationships. In Citar-Denote stores the relationship between citation keys and note files in a cache. The cache is generated every time Citar-Denote is used, which can be slow when using thousands of references. A future version will use xref to enhance performance.
The package also provides insight into citations used in the Denote collections. The citations search mechanism already uses the xref system. You can improve the search process by installing ripgrep and setting xref-search-program to ripgrep.
The citar-denote minor mode configures Citar to use the Citar-Denote functionality by defining the functions to create notes and link them to a bibliographic item.
Citar-Denote integrates with Citar and provides a series of commands specific to Denote files:
- Create a new bibliographic note:
citar-create-note - Open existing bibliographic note:
citar-denote-open-note - Open attachments, URLs or other associated notes:
citar-denote-dwim - Open bibliographic source file:
citar-denote-open-reference-entry - Convert existing notes to bibliographic notes:
citar-denote-add-citekey - Removing references from bibliographic notes:
citar-denote-remove-citekey - Find Denote file citing the current reference(s):
citar-denote-find-reference - Find a citation in Denote files:
citar-denote-find-citation - Link to a bibliographic note:
citar-denote-link-reference - Cite entries not referenced or cited in any note
citar-denote-cite-nocite - Create a new note for entries not referenced or cited in any note:
citar-denote-reference-nocite
Open the Citar interface (citar-create-note), select the entry you want to create a note for, and hit ENTER.
The default name for a new note is the title of the bibliographic entry. You can modify this behaviour with the citar-denote-title-format variable. Four options are available:
title: Extract the title from the bibliographic item (default)author-year: Use citation format as “author(s) (year)” (or editors when no authors are defined)author-year-title: Concatenate the first two optionsfull: Full citation of the entrynilor any other string: The BibTeX citation key
Using "author-year" for entries with one or more authors results in respectively:
- Benjamin (2018)
- Rensink and Kuhn (2015)
For entries with three or more authors, you can specify the maximum number of names (citar-denote-title-format-authors), which is 1 by default, and the connecting term (citar-denote-title-format-andstr), which is “and” by default.
For example, Coppa, Hass, Peck, Burger (2008) Performing Magic on the Western Stage: From the Eighteenth Century to the Present, Palgrave Macmillan. The full citation has four authors. This is rendered as:
- “Coppa et al. (2008)”: Default behaviour
- “Coppa, Hass & Peck et al. (2008)”: Three authors and “&” as connecting term
All authors will be listed if citar-denote-title-format-authors is greater than the number of actual authors. For example: “Coppa, Hass, Pech and Burger (2008)” when the maximum number of authors is equal to or greater than four.
The package uses the default file type set by the denote-file-type variable, which you can override with citar-denote-file-type to use a different file type for bibliographic notes.
The bib file tag is added by default. This tag is required to minimise the search space when caching notes. The citar-denote-keyword variable lets you change the tag to something else. Changing the default requires updating existing bibliographic notes, as the package only recognises a single string.
The citar-denote-use-bib-keywords variable lets you include keywords defined in the bibliography as Denote keywords. When set to a non-nil value, the package extracts the available keywords from the BibTeX file keywords field.
If you like storing your bibliographic notes in a specific subdirectory, set the citar-denote-subdir variable to t. When this variable is non-nil, Denote asks for a subdirectory when creating a new bibliographic note.
The package adds the reference to the front matter, e.g. #+reference: einstein_1905 for an Org Mode file. This line and the file tag link relate the note file to the BibTeX entry. Any changes to this line or the bibliography file tag break that link.
Each reference can have multiple notes, and each note can have multiple references, separated by a semicolon. For example, you could create a note about each book chapter or write a single literature review note for various papers. You must enable this option by setting the citar-open-always-create-notes variable to t.
Use citar-denote-open-note to open the bibliographic menu. Citar only shows entries that have one or more associated notes. Hit enter and select the Denote Notes you like to open.
The citar-denote-dwim function provides access to the Citar menu from where you can open attachments, other notes and links related to the citation references associated with the current buffer.
If there is more than one reference, then select the reference and then the attachment, URL or note you like to access and hit ENTER. When only one reference is present, the first step is skipped.
The citar-denote-open-reference-entry function opens the bibliographic entry (BibTex, BibLaTeX or CSL file) for a selected reference.
The citar-denote-add-citekey function adds citation keys or converts an existing Denote file to a bibliographic note. When converting a regular Denote file, the function adds the bib keyword to the front matter and renames the file accordingly.
The function opens the Citar selection menu and adds the selected citation keys to the front matter. Use the TAB key to select multiple entries.
This function can also be used to add references to existing bibliographic notes.
You remove citation references with the citar-denote-remove-citekey command.
The bibliography keyword is also removed when removing the last reference, and the file is renamed to reflect this change.
When reviewing bibliographic notes, finding where the references are cited within other notes can be helpful.
The citar-denote-find-reference function searches all finds instances where the selected reference from the current buffer is cited.
The citar-denote-find-citation function finds Denote files that cite a bibliographic entry.
You might want to create a Denote link that links to a file that references a bibliographic entry. The citar-denote-link-reference asks you to select a bibliographic entry for which a note exists.
If more than one note exists for the selected entry, then you also need to choose the relevant note to link to.
Two functions are available to find bibliographic references that are not cited or referenced in any note: citar-denote-cite-nocite and citar-denote-reference-nocite.
Both functions provide a list of all bibliographic entries that are neither cited nor referenced in your Denote files. You can then add one or more of these as a citation or a new bibliographic note.
This package is available in MELPA. You can install it with John Wiegley’s Use-Package:
(require 'citar-denote)
(citar-denote-mode)You can bind the available commands to your preferred keyboard shortcuts, following the suggestion in the Denote manual, you could use:
(let ((map global-map))
(define-key map (kbd "C-c n c c") #'citar-create-note)
(define-key map (kbd "C-c n c o") #'citar-denote-open-note)
(define-key map (kbd "C-c n c d") #'citar-denote-dwim)
(define-key map (kbd "C-c n c a") #'citar-denote-add-citekey)
(define-key map (kbd "C-c n c k") #'citar-denote-remove-citekey)
(define-key map (kbd "C-c n c e") #'citar-denote-open-reference-entry)
(define-key map (kbd "C-c n c r") #'citar-denote-find-reference)
(define-key map (kbd "C-c n c f") #'citar-denote-find-citation)
(define-key map (kbd "C-c n c n") #'citar-denote-cite-nocite)
(define-key map (kbd "C-c n c m") #'citar-denote-reference-nocite))You can use the standard Citar configuration, and there is no need to change any settings (including templates) related to bibliographic notes, as Citar-Denote takes over the note-taking functionality in Citar.
This code would only have existed with the help of Protesilaos Stavrou, developer of Denote and Citar developer Bruce D’Arcus.
In addition, Joel Lööw and Noboru Ota added significant contributions, without which this package would be useless. Finally, Guillermo Navarro, Colin McLear, Lucas Gruss, Adrian Adermon, and Jonathan Sahar provided valuable suggestions to extend the functionality.
Feel free to raise an issue here on GitHub if you have any questions or find bugs or suggestions for enhanced functionality.