Taking notes about the articles and books you read is essential to intellectual life. Many note-taking systems can connect to a bibliographic database (such as a plain text BibTeX file or external software such as Zotero). These databases are helpful when you need to add citations to your writing. Electronic bibliographies also help you create and find notes related to your literature collection and provide access to related materials, such as online sources and files stored on your computer.
Citar-Denote integrates the Citar bibliography package with the Denote note-taking system: Denote Citar lets you browse and act on bibliographic data in BibTeX, BibLaTeX or JSON format. Denote is a versatile Emacs package for taking and managing notes. Combining these two packages enables linking notes in your Denote collection to your bibliography, providing a complete solution for documenting literature reviews.
A bibliographic note is a file that refers to one or more pieces of literature in your bibliography. The notes and the entries in your literature database are intrinsically linked, making it easy to move between them. Two types of relationships exist between your notes and your bibliography:
- Reference: Relates the whole file to one or more publications (a bibliographic note). Indicated by the reference line in the front matter and the
bibkeyword. - Citation: A citation inside a note mentions one or more publications. A citation relates a portion of the note’s content to a publication.
The Citar-Denote package maintains a many-to-many relationship between your notes and your bibliography. Each item in the bibliography can have one or more notes, and each note can reference one or more pieces of literature.
You can create several atomic notes for each publication or write a complete literature review of a collection of references within one note. For example, you could write a note about each book chapter or a single literature review note for a collection of journal articles.
The system requires a stable link between the collection of notes and the bibliography to enable references. The most common behaviour for bibliography packages in Emacs is that the filename for the relevant note includes the citation key to link it to the bibliography (e.g., marcuse_1969_essay.org). However, Denote follows a strict naming convention, so this approach to linking notes and literature is not feasible.
In Citar-Denote, the citation key is part of the front matter of Denote files through the #+reference: line.
Citar-Denote stores the relationship between citation keys and note files in a cache. The package regenerates this cache after you edit a bibliography file or call any Citar functions. Each bibliographic note is marked with the configurable _bib file tag (citar-denote-keyword). This tag reduces the search space to generate the cache.
The front matter for a bibliographic Org mode note looks something like this:
#+title: Marcuse: An Essay on Liberation
#+date: [2022-11-12 Sat 19:23]
#+filetags: :bib:culture:marketing:philosophy:
#+identifier: 20221112T192310
#+reference: marcuse_1969_essay
The package also provides insight into citations used in the Denote collections. You can cite a bibliographic entry in a Denote Org mode note with the org-cite-insert function. Org mode citations
Open the Citar interface with citar-create-note. The letters at the start of the Citar menu indicate whether the entry has a link (L), note (N), attachment (F) or is cited in the current buffer (C). Select the entry you want to create a note for and use the TAB key to select more than one reference. Hit Return and follow the prompts to create a new note.
If a note already exists, you can open it. To enable multiple notes for bibliographic items, set the citar-open-always-create-notes variable to t.
Various configuration options are available to fine-tune and determine how Citar-Denote creates bibliographic notes.
You can create bibliographic notes for each file type that Denote supports: Org mode, two Markdown flavours and plain text.
Citar-Denote 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.
Please note that the citation functionality only works in Org mode. Citation mechanisms exist for Markdown, but these are not standardised.
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 entry- Fallback option or
nil: The citation key
For example, using this citation: Coppa, Hass, Peck, Burger (2008) Performing Magic on the Western Stage: From the Eighteenth Century to the Present, Palgrave Macmillan https://doi.org/10.1057/9780230617124. The five options result in:
title: “Performing Magic on the Western Stage: From the Eighteenth Century to the Present”.author-year: “Coppa et al. (2008)”.author-year-title: “Coppa et al. (2008) Performing Magic on the Western Stage: From the Eighteenth Century to the Present”.full: “Coppa, Hass, Peck, Burger (2008) Performing Magic on the Western Stage: From the Eighteenth Century to the Present, Palgrave Macmillan”.nil: “coppa_2008_perf”.
Using author-year for entries allows for some further configuration. For entries with more than one author, you can specify the maximum number of names with citar-denote-title-format-authors, which is one by default. When the number of defined authors exceeds the number in the citation, “et al.” is added to the end. All authors are listed when this variable exceeds the number of defined authors.
The default term between authors is “and”, which can be changed by customising citar-denote-title-format-andstr.
For example, when using up to three authors and “&” as a connecting term, the title for the example above becomes “Coppa, Hass & Peck et al. (2008).”
Every new bibliographic note includes the bib file tag. This tag minimises the search space when caching notes to accelerate the process. The citar-denote-keyword variable lets you change the tag to something else. For example, if your primary language is Welsh, you might want to change it to llenyddiaeth (literature).
Changing the default keyword requires updating all your bibliographic notes because the package only recognises a single string. The Denote-Explore package provides a function to rename Denote keywords. Denote-Explore
The citar-denote-use-bib-keywords variable lets you include any keywords defined in the bibliography entry in the note. When set to t, Citar-Denote extracts the available keywords from the BibTeX keywords field and uses these as Denote file tags.
All new notes are stored in the location specified by denote-directory.
If you like storing your bibliographic notes in a subdirectory, set the citar-denote-subdir variable to t. Denote now asks for a subdirectory when creating a new bibliographic note.
When the content of this variable is a string, Denote saves the note in a subdirectory with that name under denote-directory. For example, if this variable is set at “literature”, all bibliographic notes are stored under denote-directory/literature/.
When the citar-denote-signature variable is 'ask, Denote will ask for a signature when creating a new bibliographic note.
When this variable is set at 'citekey, the citation key forms the basis of the signature. Please note that Denote changes or remove punctuation marks in the citation key with denote-sluggify-signature to enforce compliance with its file naming convention.
For example, when the citation key is einstein_1905, the signature becomes einstein=2005.
Denote allows you to create templates for various types of notes. You could use standard headings for bibliographic notes, other headings for meta notes, or whatever else you might need, Denote templates
To include templates in new bibliographic notes, set the citar-denote-template to either:
t: Ask for a template when creating a note.- The name of the default template for creating bibliographic notes
The example below lets the user choose between a note with two headings (Abstract and Review) or a plain note without any template content when citar-denote-template is non-nil. Setting citar-denote-template to biblio will always use this template for new literature notes.
(setq denote-templates
'((biblio . "* Abstract\n\n* Review")
(plain . nil))
citar-denote-template 'biblio)If you have a set of notes from the same book and use Org mode, you can create a meta note to combine the relevant notes. This note can have automated links to all related references with dynamic blocks or transclude the note’s content.
The best way to create a meta note that combines literature notes from a single publication is to add the citation key in the signature, as explained above. You can then use the signature as the regular expression for the block.
Other options include creating a meta note for an author or a specific subject matter. You can use dynamic blocks if the relevant notes all include the same character string in their file names, which you can fetch with a regular expression. For more information on meta notes, Writing metanotes
Once you have some bibliographic notes, you will want to access and modify them. You can access the attachments, links and other notes associated with the references from within via the Citar menu (citar-open). Entries with a note are indicated with an N in the third column.
There are two entry points to finding notes related to literature, either as references or as citations.
Use citar-denote-open-note to open the Citar menu with only entries with one or more associated notes. Select your target and hit Return.
Citar provides a list of resources for the selected entry: attachments, existing notes, links and an option to create an additional note. Select the note you seek, hit Return again and select the Denote file you want to open.
The previous function shows all literature with one or more bibliographic note(s) linked through a reference line. The citar-denote-find-citation function lists all bibliographic entries cited inside your Denote collection, from which you can open the relevant note.
When only one note cites the selected entry, this file is opened. When multiple files cite the chosen entry, you must pick which file to jump to.
By default, this function only looks at citations in your document. Setting the citar-denote-cite-includes-reference to non-nil includes references.
When using the citar-embark package, you can activate this function with Embark after you create a keyboard shortcut.
(define-key citar-embark-citation-map "c" 'citar-denote-find-citation)
Depending on the size of your digital garden, searching through all your notes for citations can take a moment. The citations search mechanism uses the xref system. You can improve the search process by installing the faster ripgrep program and setting xref-search-program to ripgrep.
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 Denote buffer.
Select the required bibliographic item when there is more than one reference. You can then select the attachment, link, or note you would like to access and hit Return, after which you will choose your link, note, or attachment. Alternatively, you can also create a new note for that reference.
The citar-denote-open-reference-entry function opens the bibliographic entry (BibTeX, BibLaTeX or CSL file) for a selected reference, from where you can edit the bibliographic data.
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.
This function opens the Citar selection menu and adds the selected citation keys to the front matter.
You remove citation references with the citar-denote-remove-citekey command. Suppose the current buffer references more than one piece of literature. In that case, you must select the unwanted item in the minibuffer.
When no more reference items are left, the _bib keyword is removed, and the file is renamed.
You can also manually edit your file and add and remove reference citation keys.
Bibliographic notes rarely exist in solitude. A note might be one of a series about the same topic or about the same book.
The citar-denote-find-reference function finds all notes where another note cites the selected reference from the active buffer. A warning appears in the minibuffer when the selected reference is not found in any Denote files or you are not in a Denote file.
If you would like to know whether one of the references in the current buffer is also referenced in another note, then use citar-denote-dwim, discussed above.
Denote has excellent capabilities for linking notes to each other. You can use this facility to link to any other bibliographic note in your collection. The citar-denote-link-reference function asks you to select a bibliographic entry for which a note exists and create a link to the relevant note in the current Denote buffer. If more than one note exists for the selected publication, you first choose which note you like to link to.
What is the point of building a bibliography without using each entry as a citation or a reference in a bibliographic note? The last two functions let you cite literature or create a new bibliographic note for any item not used in your Denote collection.
The citar-denote-nocite function opens the Citar menu. It shows all items in your bibliography that are neither cited nor referenced. From there, you can create a new bibliographic note, follow a link or read the associated file(s). If your Denote collection references or cites all items in your bibliography, a message appears in the minibuffer: “No associated resources”.
The citar-denote-cite-nocite function cites an unused bibliographic entry. This function only works when the active buffer is a Denote Org mode note.
Lastly, the citar-denote-nobib function lists all references and citations in your Denote collection that are absent in the global bibliography in the *Messages* buffer. Note that this list excludes any local bibliographies. The output of this function is a list of citation keys used in Denote that need to be added or corrected.
This package is available in MELPA. The example below provides a minimum configuration for Citar and Denote. The minimum required configuration for Citar is to set the list of bibliography files. Using Org mode citations, you can set this variable the same as org-cite-global-bibliography. This configuration also sets Citar to accept multiple notes per reference.
(use-package citar
:ensure t
:defer t
:custom
;; set bibliography's location
(citar-bibliography '("~/documents/library/magic-tricks.bib"))
;; Allow multiple notes per bibliographic entry
(citar-open-always-create-notes nil)
:init
(fido-vertical-mode 1)
:bind ("C-c w c" . citar-create-note))
(use-package denote
:defer t
:custom
(denote-directory "~/documents/notes"))The citar-Denote configuration includes all configurable variables with their package defaults. You can either remove these entries or configure them to your preferences. This configuration example also binds all available Citar-Denote commands. You will need to change the directory paths to suit your preferences.
(use-package citar-denote
:ensure t
:demand t ;; Ensure minor mode loads
:after (:any citar denote)
:custom
;; Package defaults
(citar-denote-file-type 'org)
(citar-denote-keyword "bib")
(citar-denote-signature nil)
(citar-denote-subdir nil)
(citar-denote-template nil)
(citar-denote-title-format "title")
(citar-denote-title-format-andstr "and")
(citar-denote-title-format-authors 1)
(citar-denote-use-bib-keywords nil)
:preface
(bind-key "C-c w n" #'citar-denote-open-note)
:init
(citar-denote-mode)
;; Bind all available commands
:bind (("C-c w d" . citar-denote-dwim)
("C-c w e" . citar-denote-open-reference-entry)
("C-c w a" . citar-denote-add-citekey)
("C-c w k" . citar-denote-remove-citekey)
("C-c w r" . citar-denote-find-reference)
("C-c w l" . citar-denote-link-reference)
("C-c w f" . citar-denote-find-citation)
("C-c w x" . citar-denote-nocite)
("C-c w y" . citar-denote-cite-nocite)
("C-c w z" . citar-denote-nobib)))You can use the standard configurations for Citar and Denote. Citar-Denote takes over the note-taking functionality in Citar with a minor mode.
You can also install this package directly from GitHub to enjoy the latest version (assuming you use Emacs 29 or above.
(unless (package-installed-p 'citar-denote)
(package-vc-install
'(citar-denote
:url "https://github.com/pprevos/citar-denote/")))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 made significant contributions, without which this package would not exist. Troy Figiel, Taha Aziz, Ben Ali, Guillermo Navarro, Colin McLear, Lucas Gruss, Adrian Adermon, Jonathan Sahar, Samuel W. Flint, Yejun Su, and Elias Storms provided valuable suggestions to extend functionality.
Feel free to raise an issue here on GitHub if you have any questions or find bugs or suggestions for enhanced functionality.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License or (at your option) any later version.
This program is distributed in the hope that it will be useful but WITHOUT ANY WARRANTY, INCLUDING THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
For a full copy of the GNU General Public License, see https://www.gnu.org/licenses/.