Customize the rendering of inline references - Spec
Problem
Currently, all inline references are rendered in the same exact way, like this:
@dijkstraNoteTwoProblems1959
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.
Solution
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:
@dijkstraNoteTwoProblems1959
This is shown by Dijkstra (1959).
[@dijkstraNoteTwoProblems1959]
This is shown by (Dijkstra 1959).
-@dijkstraNoteTwoProblems1959
This is shown by -Dijkstra (1959).
[-@dijkstraNoteTwoProblems1959]
This is shown by (1959).
-[@dijkstraNoteTwoProblems1959]
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.
Implementation
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.
!