Introduction to customising Joplin (userchrome.css & userstyle.css)

Joplin has several internal stylesheets that control what Joplin looks like to the user. However two have been provided that allow the user to customise the app. Joplin uses its built-in styles but these two files can be used to override those styles. These files are just like the Cascading Style Sheets (CSS) used when creating web-sites. The files are called userchrome.css and userstyle.css.

  • userchrome.css allows styling of the app itself, including the Markdown Editor,
  • userstyle.css allows styling of the Markdown Viewer Pane / Rich-text editor.

Although css changes for the Markdown Viewer Pane and the Rich-Text Editor are written into the same userstyle.css file, that does not mean that the change you have made will automatically work in both. There may be subtle differences in the css elements used by the Markdown Viewer Pane and the Rich-text editor for the item you wish to modify.

The pictures below highlight the areas covered by each stylesheet.


Markdown Editor with Viewer Pane


Rich-text Editor

Both these files can be accessed from within Joplin by going to the settings page and navigating to Appearance > Show Advanced Settings and pressing "Custom stylesheet for rendered Markdown" (which opens userstyle.css) or "Custom stylesheet for Joplin-wide settings" (which opens userchrome.css). The files will be opened by whatever app on your system is set to open .css files. The css files are plain-text files so if there is not an app set and you are asked by your operating system to pick one, choose a plain text editor.

The actual location of the files is ~/.config/joplin-desktop on Linux / MacOS systems and C:\users\<username>\.config\joplin-desktop on Windows systems. If you have not already opened the css files from within Joplin they initially may not exist in the folder and so will need to be created manually. Do not touch any other files in this folder, they have nothing to do with styling Joplin and could corrupt your Joplin data if tampered with.

It is important to note that these custom stylesheets are loaded as Joplin is started. If you modify either of the stylesheets you have to quit and restart Joplin for the changes to take effect. That is not just closing the Joplin window, it requires Joplin to be Quit (File > Quit or CTRL+Q).

Also as these are just styling modifications, if you make a mess you can simply delete the stylesheets or the contents of the stylesheets. Then quitting / restarting Joplin will bring Joplin back to normal.

Finding the names of the things you want to change

Of course none of this is any good if you cannot find the names of the elements you wish to customise.

If you click "Help" on the Joplin toolbar there is an option in the menu to "Toggle Development Tools". This will open a window that shows what is going on under the surface of Joplin. Selecting the “picker” ([1] in the below picture) will allow you to use the cursor to point at a part of the Joplin interface you are looking to customise. This will show a flyout ([2] in the picture) and the code ([3] in the picture) that can help you to determine the element / class you wish to modify.


Development tools

Search this forum and you will find many examples to try out, modify and learn from. This page is a good starting point. Initially it's not an easy thing to do if you do not have much experience of using stylesheets. But over time the logic becomes clearer and it does become a bit easier. Sites such as "w3schools CSS reference" are useful to gain familiarity with the terms you encounter when looking at CSS.

Important

This ability to customise Joplin is considered an "unsupported" feature. This basically means that if a custom stylesheet does not work as you expect or there does not appear to be a way to modify a particular part of Joplin, it's not a bug. Being unsupported also means Joplin has no obligation to maintain compatibility with any custom stylesheets. As Joplin develops, the names of the style elements could change (and they have in the past) and your custom stylesheet may no longer fully work. So it's up to the user to maintain compatibility. That also means that when browsing the forum for ideas, there is a possibility that examples in old posts will not work.

This also means that any support for customising Joplin is provided on this forum by other users. If you get stuck please search this forum and the Internet first and try your best. It can be a lot easier and quicker for someone to help you correct what you have achieved so far, rather than have to explain everything from the beginning.

27 Likes