Customize the rendering of inline references - Spec

Customize the rendering of inline references - Spec


Currently, all inline references are rendered in the same exact way, like this:

While this is okay as a starting point, it is certainly not enough to fulfill users' demands. We need a way for users to choose how their inline references get rendered. For example, I might want an inline reference to look like this:
This is shown by Dijkstra (1959).
or like this:
This is shown by (Dijkstra 1959).

In addition, there should be a default way to render them such that users don't have to specify the style every time they insert a new reference.

More info


In order for users to customize the rendering of inline references, there are two options for them to do so. The first approach is to use Joplin-wide settings to set how references look. I discourage this approach because it applies the same style to all references in all notes, and users cannot specify a format for each reference independent of the others. The second possible method is to make users take control of how every single reference gets rendered by modifying the markdown text that was used for that reference. I prefer this method because it's more user-friendly, flexible, and customizable.

One piece of software that does the exact same thing is Pandoc. Pandoc allows users, through its CLI, to control how every reference gets rendered (converted to other formats) by modifying the markdown that was used to generate the reference. Here's a subset of the formats supported by Pandoc and their corresponding markdown syntax:

This is shown by Dijkstra (1959).

This is shown by (Dijkstra 1959).

This is shown by -Dijkstra (1959).

This is shown by (1959).

This is shown by -(Dijkstra 1959).

@dijkstraNoteTwoProblems1959 and @dijkstraNoteTwoProblems1959
This is shown by Dijkstra (1959) and Dean (1997).

[@dijkstraNoteTwoProblems1959 and @deanFindingOptimalRoutes1997]
This is shown by Dean (1997).

[@dijkstraNoteTwoProblems1959; and @deanFindingOptimalRoutes1997]
This is shown by (Dijkstra 1959; and Dean 1997).

[@dijkstraNoteTwoProblems1959; and -@deanFindingOptimalRoutes1997]
This is shown by (Dijkstra 1959; and 1997).

@dijkstraNoteTwoProblems1959 [p. 33]
This is shown by Dijkstra (1959, 33).

@dijkstraNoteTwoProblems1959 [pp. 33-35, 38-39]
This is shown by Dijkstra (1959, 33–35, 38–39).

@dijkstraNoteTwoProblems1959 [chap. 1 pp. 33-35]
This is shown by Dijkstra (1959, chap. 1 pp. 33-35).

This list was contributed by @Klemet.

The syntax used by Pandoc to format references is detailed and well-defined. In an ideal scenario, the whole set of formats is implemented and works correctly without conflicting with each other.


For this feature to work properly, I will have to include a new markdown-it rule to handle every format on its own. This will may be done in a new content script.

How to detect the syntax of every format?

Search through all the tokens recursively using DFS and utilize Regular expressions to catch the desired syntax.

Possible optimizations

I'm yet to investigate this matter, but I think catching all the formats in a single rule is more optimized than creating a rule for every single format.

Possible Bugs

There may be some conflicts between BibTeX Plugin and other plugins or even between the rules themselves.

1 Like

How standard are these Pandoc rules? Because they seem very unintuitive to me. Also by supporting this, the reference will no longer be a regular link, which has the nice side effect of working even when the plugin is not installed.

Hmm, now we have a trade-off between compatibility and feature-richness.
Can we balance this trade-off by setting the default markdown text be:


which ensures backward compatibility with previous versions of the plugin. In addition, if the user wants to customize the style, then he can choose whatever style from the above list.

1 Like

Yes I guess that would be a good compromise.

1 Like

Hello, Laurent ! First time that I'm talking to you here, but I just wanted to quickly say how much of a fan I am of Joplin. Thank you so much for this amazing software !

From the little that I know, this citation syntax is currently used by Pandoc, by RMarkdown (which uses Pandoc, if I remember correctly), but also by Zettlr (even if the implementation of Zettlr is not complete; but it's still the same type of syntax).

Hence, from what I've seen so far, this syntax is currently the most used for using citations in the world of markdown. I personally think that it makes a good compromise between the customization options that it allows for in-line citations, and the complexity of the syntax. In the end, I think that most people will only use @citekey and [@citekey] (which should display Smith et al., XXXX and (Smith et al. XXXX) respectively).

1 Like

This looks like a great idea to me !

I'd maybe propose a small twist, though; with Pandoc or with RMarkdown, if I remember correctly, in-line citations are a link that gets the users to the right reference in the "reference" section at the end of the document (basically an anchor link ?). From there, the DOI link is often displayed in the full reference, allowing the user to click on it if needed. If not, a small arrow can allow the user to go back to where they were in the text (like is the case for footnotes).

I think that this solution might be a better one, as it seems to fulfill all needs:

  1. The citations are still a link that can be displayed if the plugin is not installed.
  2. The in-line citation can be customized if the plugin reads what's inside the square braquets of the link.
  3. If there is no DOI or URL associated with the reference (which can happen more often than we think), the plugin will still make a link to the reference section. That way, there is no risks of having an empty link, or of forcing the user to input a URL for the reference.
  4. It also makes the potential back-and-forth with the references section much easier to deal with, and gives more importance to the reference section (why scrolling down to the references section if every in-line citation is a link with the DOI of the document that you can click ?).

Thank you so much for your work, I'm very impatient to see it complete :smiley: !

1 Like

This sounds like a good idea to me. However, I cannot yet implement that until I have opinions from other users (maybe by doing another survey).
Thanks a lot :slight_smile:

1 Like

On any device the plugin is not installed (all mobile devices) there is no reference section. I don't see this helpful as a default behavior for myself.
I myself don't even need a reference section most of the times. Only an inline citation is enough and there the direct link is very powerful.
Possibly a setting to choose the field entry (DOI, URL, URI) of the Bibtex file or to be able to set the order of links it should look for could be very powerful.

That's a great point ! Then the current option could be great, then : ).

1 Like

Hello, I was looking for this feature and got here, just wondering whether it happened/will happen soon