Since I use an iPad as my device of choice when working away from home, I have been looking to find a way to insert citations while writing in the iOS Obsidian app.
The problem
Unfortunately, none of the three plugins for Obsidian that can insert pandoc citekeys work on mobile:
- Citations: Currently desktop only, and until recently, development had apparently stalled. There has been no update for 9 months, and a two-year-old issue about mobile support has been marked “Help wanted” for a year.
- Zotero Integration: Used to be called Desktop connector (hint, hint)—it is not available on mobile. It needs to have Zotero running to work, so it is unlikely to ever be available on mobile.
- Obsidian-Zotero: Has mobile support on @aidenlx’s Github roadmap, but it’s unclear how that will be implemented. Furthermore, updates have been slow lately, despite many bugs.
The solution
Enter Various Complements to the rescue!
Various complements
This plugin enables you to complete words in Obsidian like the auto-completion of IDE.
The key feature of Various Complements that we will use is autocompletion based on Custom dictionaries.
I got this idea from these underappreciated iOS Shortcuts for Textastic from @somelingust on GitHub, which enable citation autocompletion in Textastic.
This was the most satisfactory way to insert citekeys that I could find for the iPad.
However, it required me to switch back and forth between Obsidian and Textastic. Furthermore, Textastic only autocompletes based on the start of the citekey, so I couldn’t search by title.
Various Complements is much more customizable in its autocompletion, offering fuzzy matching of both the prefix and partials of a string. And, it can match aliases you set, which will come in handy.
Demo
Creating a citation dictionary
The starting point for this workflow is an exported reference library, in the form of a bibtex file.
Next, we need to convert the bibtex bibliography into a custom dictionary that Various Complements can read. The data should be in a format like this:
inserted text, description, alias
In our case, we want to insert the citekey, and use the title as both description and alias, like so:
citekey, title, title
Yes, title twice. Why? The first instance of title is only for display in the dropdown, while the second one is a searchable alias. With this format, we can search for and autocomplete citekeys using either the citekey or the title.
I’ve made a script in Javascript that handles the conversion from bibtex file to custom dictionary in the format above.
The script
Copy the script using the button in the upper right corner.
const fs = require('fs');
function extractCiteKeysAndTitles(bibtexFile) {
const bibtexData = fs.readFileSync(bibtexFile, 'utf-8');
const regex = /@([a-zA-Z]*)\s*\{\s*([a-zA-Z0-9_:.#$%&-+?<>~/]*),.*?^\s*title\s*=\s*[\{"](.*?)[\\}"],$/gmis;
let match;
let markdownContent = '';
while ((match = regex.exec(bibtexData))) {
const citeKey = match[2].trim();
const title = match[3].trim().replace(/[\{\}]/g, "");
const formattedTitle = convertTextendash(title);
markdownContent += `@${citeKey}, ${formattedTitle}, ${formattedTitle}\n\n`;
}
return markdownContent;
}
function convertTextendash(title) {
// Convert "\textendash" to en-dash symbol
const enDashSymbol = "–";
return title.replace(/\\textendash/g, enDashSymbol);
}
// Usage
const bibtexFile = "Path/to/bibtex-bibliography.bib";
const markdownContent = extractCiteKeysAndTitles(bibtexFile);
return markdownContent;
Running the script
To run the script inside Obsidian, we will use Quickadd’s inline scripts.
Ironically, the first part of generating the citation dictionary using Quickadd must be done on a desktop computer. The setup of Various Complements is done on the mobile device.
In the future, I hope to refactor the script, so it can be run on mobile devices (see the section below on improvements). Anyway, here’s what you need to do:
-
As mentioned, you need to export a bibtex bibliography (preferably into your Obsidian vault) first.
- If using Zotero, right-click a Zotero collection → Export Collection.
- Note: I used the BetterBibtex format when testing, which requires the Better Bibtex addon for Zotero. Regular bibtex might work too, but I haven’t tested it.
-
If you haven’t already, create a folder for all your templates. Then supply this path in QuickAdd’s
Template folder pathsetting. -
Copy and paste the script above into a new markdown file in the Template folder of your vault.
- Name the file something like “citation-dictionary-creator.md”
- The code should be pasted inside a code-block that starts with
js quickaddlike so:
-
Replace
"Path/to/bibtex-bibliography.bib"in thebibtexFileconstant of the script with the actual path where you exported your .bib file. -
Add a Quickadd template choice and call it something like “Create citation dictionary”
- See Quickadd’s first steps for help, if necessary.
-
Click the gear icon next to the newly created template choice:
1.
-
Set up the template choice in Quickadd as follows:
1.
- Make sure to pick the “citation-dictionary-creater.md” template, which contains the script.
-
Run the new Quickadd template choice called Create citation dictionary
- Command palette → Run QuickAdd → Create citation dictionary
- For me, the script runs very quickly, converting a bibtex file with 1800 references into a custom dictionary in just a few seconds.
-
On the mobile device, enable the Custom dictionary complement setting in Various complements.
- Make sure that the citation-dictionary.md file has been synced to your mobile device using your syncing method.
-
Put the relative path of the citation dictionary created by the script into the Custom dictionary paths text box:
1.
- Make sure that the column delimiter is set to “comma”.
Now, you should be ready to cite on your mobile device 
Simply type
@and then either the citekey or title of the item you are looking to cite. This will trigger a dropdown tooltip from by Various complements, giving you a list of matches.
Automation
Automating the process of updating the citation dictionary every time Obsidian opens is simple. Just configure a macro in QuickAdd’s settings:
- Press
- Name the macro and add it:
- Enable
Run on plugin load:
- Press
Configureand add the previously created QuickAdd template choice to the macro:
Done! Now the citation dictionary will always be up-to-date once you’ve opened Obsidian on your desktop device.
Citation dictionary example
Here’s an example of what the resulting citation dictionary looks like. It goes on for another 1800 entries in my case.
Customization
Citation format
If you want to customize the script, let’s say, to change the autocompleted citekey format to be surrounded by square brackets, you can do that by changing the following line in the script:
markdownContent += `@${citeKey}, ${formattedTitle}, ${formattedTitle}\n\n`;
to this:
markdownContent += `[@${citeKey}], ${formattedTitle}, ${formattedTitle}\n\n`;
Recommended Various complements settings
- Increase Max number of suggestions to see more suggestions without having to scroll.
- If you are not interested in the other types of autocompletion that Various complements enables, you can disable those under the settings.
Limitations
Conflict with other citation autocompleters on desktop
In case you use Pandoc Reference List, the autocompletion of Various complements will interfere with its citekey autocompletion, if both are enabled.
@mgmeyers recently moved the citation autocompletion feature from Zotero Integration to Pandoc Reference List. He is the maintainer of both plugins.
That’s why you’ll want to create a settings profile for mobile using the Settings → About → Override config folder setting and set it to something like .obsidian-mobile.
This way, you can have a Various complements installation and configuration that only affects your Vault on the mobile device, without interfering with Pandoc Reference List on your desktop device.
No modifier key for alternative citation formats
Another limitation is that I haven’t figured out a way to easily insert an alternative citekey format, for example when pressing a modifier key.
One option would be to create two entries in the bibliography dictionary, one in each format. Then, you could insert the one you wanted from the tooltip drop-down. However, this might not work as intended, so I’m sticking with manually adding square brackets, until I figure something out.
One way to make this easier is to use the Smarter Markdown Hotkeys plugin, which has a Smarter Square Brackets command. It adds square brackets to your selection, which doesn’t have to be precise (you can select part of a word, and it nevertheless applies the formatting to the whole thing).
Planned improvements and feedback request
I plan to change the script so that it uses the Quickadd API / Obsidian API to read the bibtex file, rather than using the file system module (‘fs’) from Node.js.
This way, it should be possible to run the script on the iPad. This would be more convenient and less ironic than a mobile workflow that requires a desktop computer. Nevertheless, a desktop computer would still be required to export the library from Zotero, so it shouldn’t be too inconvenient to also run the script on a desktop computer.
I would appreciate any feedback and ideas on how to improve this workflow and the script. Especially regarding how to refactor the script to use the Quickadd/Obsidian API, and on how to implement a convenient way to insert an alternative citation format.
Also, please report back if you encounter any issues.
