Week 1: Custom Keyboard Shortcuts


It’s been a long week of going through Joplin code-base, discussing with my mentors about possible changes and new ideas about the project, and researching. This is my first update of my project for Google Summer of Code 2020!

Changes to the Data Structure

My initial proposal was to use Joplin’s Setting.js model to store and retrieve custom keyboard shortcuts. (Read it here (190.2 KB)) This has some advantages, such as being simplest to implement and easy to save and retrieve.

However after some discussion I had with my mentors, it seems clear that using a similar implementation to the CLI (using a JSON file to store custom keyboard shortcuts) would be the better choice. Major advantage of this approach is, having a JSON file which is not only editable via Joplin Options panel but also manually, if needed. Also, one can use the same JSON file between multiple devices, or even share them with others on the forum. (Read more on here)

There’s another aspect we need to think about in this approach. Joplin Electron app shares the same code on Linux, Windows and Mac. Linux and Windows has almost the same keyboard layout; no issue with that. But Macbooks have a different keyboard layout.

Luckily, Electron’s Accelerators do much of the hard work. All we have to do is, when a user presses a key combnation, generate a cross-platform Accelerator string so that the JSON file can be used interchangeably on any type of PC.

This can be done by following conditional transforms:

  • Convert Ctrl or Command to CommandOrControl (In most apps Ctrl and Command keys are basically used as the same key)
  • Convert Option to Alt (Alt is compatible with all platforms)

And voila! You have a platform-agnostic Accelerator!

User guide

The CLI has a nice guide for keyboard shortcuts. Since this project enables manually setting up shortcuts, I think something like that would be nice to have. I’ll start working on this once the basic implementation is complete.

Future improvements

Electron apps have a limitation of sort when using Accelerators for defining keyboard shortcuts. It needs to be bound to a menu item. What if we want a keyboard shortcut for an action that is not in the menu?

If such issue occurs in the future, electron-localshortcut is a library built to solve this exact issue, and it also works on Accelerators. It means that even if Joplin gets keyboard shortcuts that don’t have their own menu item, it can still utilize the soon-to-be-implemented keyboard shortcut editor!

What’s next?

Most of the details have been sorted out. I think I’ll start the implementation early on, giving me more time to work on stuff and test out various things.

Thanks to my mentors @bedwardly-down and @tessus, and @laurent for the guidance and awesome support, and thank you for reading! Feel free to give any feedback or new ideas on the project.

Stay safe!


Thanks for the update Anjula, it’s all looking good so far. Whenever you have some code that works and is self-contained, feel free to submit a pull request. In general, it’s better to split the progress into multiple independent pull request as it is easier to review.

I might be wrong, but I suspect you won’t need this because if the item is not in the menu then I think it should be added. The good thing with menu items that it’s self-documenting - it tells what actions are possible and what the shortcuts are, without having to read the documentation. So let’s see, if you get to a point where electron-localshortcut is needed, let’s discuss it but otherwise a solution where actions are added to the menu is preferable.


That library also pulls in 15 extra dependencies according to its npmjs page. One thing that needs to be researched before adding any new libraries is how compatible these are with current libraries already being used by Joplin.


Hopefully we won’t need to add that library!

1 Like