Custom Citation Style - Spec

Custom Citation Style - Spec

This is the specification of the feature at hand.


Currently, references are rendered at the note footer in APA format. For example,

Although this might be OK for some users, every journal wants the references supplied in a specific format (longer/shorter, with/without titles, only first author / all authors, etc.). As a result, adding an option for specifying the citation style is immensely useful. The user should be able to somehow (addressed later in this post) select the style (APA, MLA, Nature, IEEE, etc.) in which the references are rendered, and the bibliography is automatically formatted based on the chosen citation style.

More info


As in apps like Mendeley, the user selects a certain citation style from a large list, then all the references get automatically formatted according to the specified style. Under the hood, it utilizes the concept of Citation Style Language (CSL), which is an XML-based format to describe the formatting of citations, notes and bibliographies. CSL is the de facto standard for citation styling and it has a very detailed documentation. Every citation style has a CSL file which describes exactly how references written in this style should be formatted. For example, here is the CSL file of IEEE format, which is contained in a very large repository alongside other well-known citation styles.


The implementation will consist of two major parts: selecting a Joplin-wide citation style and rendering the references using that style.

Selecting citation style

There are two approaches for enabling the user to select a citation style: either to choose from a large list of well-known styles or to specify a path of a .csl file. I personally prefer the later method since it's more customizable and user-friendly, in addition to being easier to implement (by just registering a new field in the config screen). By default, there will be no path to a .csl file. In that case, the default style that shall be used is APA.

Rendering the references in the specified style

For this feature to work, there should be a utility that does the following:

  • Take two arguments: .csl file and a reference.
  • Parse the .csl file.
  • Generate an HTML markup representing the given reference in the specified format.

Such utility is already implemented and it's called a CSL Processor. There are numerous implementations of CSL Processors in various programming languages and technologies. The one that's gonna be useful for this feature is Citeproc-js or its developer-friendly cousin simple-cite, which is just a simple wrapper around Citeproc. Although having a somewhat complex interface, I think Citeproc-js is more suitable as it has been live for about 12 years, and currently used by a lot of applications (like Zotero and Mendeley).


As usual, all suggestions and ideas are welcome :smiley:
Am I missing something? Are there any ambiguous parts? How can this be improved?


What you've typed there sound absolutely perfect from my point of view.

I think that asking for a .csl file it best, as the alternative would imply a menu of possible styles to chose from that will either be outdated at one point, or will need to be updated "by hand".

Hence, good luck for this part ! And thank you for all of your hard work ! I'll start doing workshops to present Joplin to my colleagues in academia soon, and talking about this plugin will help a lot :smiley: !

1 Like

Thanks a lot, sir :smiley: