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.

33 Likes
Share your CSS
How to change the GUI fonts, font colors and font sizes to system defaults?
How can i change the color of the Background Highlight
Adding header and footers
Removing whitespace at paragraph breaks
Style customization / userstyle.css
CSS In editor / Code View - How to activate
Editor color highlighting
Material theme for Joplin 🎨
How do I change the background color for the note list pane?
Change font-family in tables (userstyle.css)
External CSS for Notes
Hide button switch Markdown and WYSIWYG
Joplin 2.7: Bold text not green anymore
How to swap the markdown and preview pane?
How to use a specific typeface for body text but a different one for headlines?
Remove Tags from UI
Note taking software exactly like Joplin but with different UI?
Css code to change background color of html note
Notes are unorganized after exporting to .pdf
How to change editor layout?
Change color of "note title" field in CSS
Editor maximum width issue
Table cell formatting
The background of code blocks is not uniform, and the background of blank lines is not gray
How to reduce line spacing on printout?
Hiding UI elements
Widen the scroll bars on Windows
What happened to overwrite after editor change
Where to find userstyle.css to change line-height
My Own Scroll Bar Styling Not Working Correctly
Share your CSS
Code block feature in the rich text editor is too unattractive
Feature request: Add option to disable "New todo" button
Question re: Inline ToDos
Userchrome.css is not being applied
BUG ? - The line is never in the exact middle
Reset or deleting joplin
Style customization / userstyle.css
How to adjust page margins
Headers all look too similar
Hide button switch Markdown and WYSIWYG
What features did you like in 2023 and what do you want to see in 2024?
Turn off fading text in todos
Note list preview plugin
Option to stop the current time from being displayed near the title prompt
Difficulty customizing userChrome.css items for settings page and notes list
Is is possible to avoid formatting in Markdown Editing
.css question
How to left align all Maths blocks (globally)?