Custom stylesheets

I’ve explained some of the challenges in the other topic (which I referenced earlier).
One thing we have to allow people is to choose the files per platform. Desktop vs Mobile.
This does not mean it shouldn’t be possible to share one css file for all clients. However, we should use a unique device identifier to allow a device css file, if wanted that is.

I would like to keep Joplin as minimalistic as possible, without too much concessions to usability. Creating two types of notes, data and configuration, is confusing to the user in my opinion and may break the architecture (e.g. search facilities). A lot can be done with the current setup. Some problems don’t have to be solved by Joplin, as they can be solved by CSS. Let’s start with considering the wishes before thinking in solutions, and weigh their importance. Here are some wishes:

  1. I want some platform-independent styling, for instance all headings being Joplin-blue.
  2. I want to adapt some styles to my platforms.
  3. I want to adapt some styles to my devices, for instance geared to their screen size and resolution.
  4. I want to style some notes in a notecategory-specific way.
  5. I want to style some notes in a notecategory×platform-specific way.
  6. I want to style some notes in a notecategory×device-specific way.
  7. I want to style some notes in a note-specific way.
  8. I want to style some notes in a note×platform-specific way.
  9. I want to style some notes in a note×device-specific way.

As far as the desktop versions are concerned, the wishes 3, 6, 7, and 9 are already fulfilled, as mentioned in my previous post. The wishes 1 and 2 have to be realized by 3, the wishes 4 and 5 by 6, and wish 8 by 9. This violates the DRY principle, but as I don’t use Joplin on hundreds of devices, it’s is not a big issue for me (but how about other users?). As for 6 and 9, I would like to have a generic way to refer to the directory .config/joplin-desktop/ where I store all my CSS files, that’s all. But even that’s not indispensable. BTW, I think 6 could also be realized by some CSS-tricks in userstyle.css (I haven’t experimented with it yet), which would make the <link> construction unnecessary.

Synchronization is only needed for 1, 4 and 7. But as 7 can be built in in the note itself, only 1 and 4 would demand for extra provisions.

And to conclude with a very personal opinion: I don’t think platform (2, 5, 8) is a very significant dimension for styling. The individual devices (3, 6, 9) with al their particular properties are far more important. But you may convince me of the contrary.

I agree. Either you haven’t read my text completely or you ignored its meaning.

However, we should use a unique device identifier to allow a device css file

So there’s a hierarchy: mobile/desktop -> OS -> device. The granularity depends on the person who will implement it. I’m all in for all levels, but I doubt that Laurent will accept this type of complexity. e.g. how to merge the levels?

Your hierarchy could be extended to mobile/desktop -> OS -> device -> screen. On further consideration, screen is a dimension of its own. So there are at least four dimensions to deal with:

  1. The cascade of stylesheets, i.e. the sequence in which style specs are processed
  2. Devices (synchronization of specs for individual devices is not needed, but for higher levels in the hierarchy it might be a nice to have)
  3. Screens (synchonization between devices might be desirable, but is not essential)
  4. Notes (are already synchonized)

I do hope that the configuration interface won’t reflect this complexity in the future. In fact, the current desktop version meets my needs to a great extent, since I can do a lot of manipulations outside Joplin. What I’m really still missing is the possibility to use references in <link> tags and hyperlinks like:

  • ./«file»
  • ~/.config/joplin-desktop/«file»
  • $HOME/.config/joplin-desktop/«file»

That would facilitate generic constructions in my notes. More has to be built for mobile devices: at least provisions for creating, editing, renaming, and deleting (and maybe copying) CSS files in some dedicated config folder. Support for hyperlinks to HTML files on the synchonization target might be another challenge. I have no ideas about that yet.

Just another wild idea: how about making userstyle.css a parametrized stylesheet? It would be possible then to make your self defined color schemes dependent on the chosen theme.

Thanks, nice discussion. So 3 other points to consider :

  1. Have a CSS editor for easy styling of the css file
  2. Give some templates (themes) that user could choose without any css coding
  3. These two features should support desktop AND mobile (styles could be different on mobile, have to use responsive design in the css - the editor could make it more easy to build)

(Just some petty facts from my side. This post was intended as an answer here to @DominicDesbiens, or in fact to anyone who is interested in where to find the built-in style definitions.)

If you know how to interpret the CSS language and know how to open a file in a safe way for reading (i.e. without the risk that you unintentionally change something), you could peek in the following file to see what’s predefined by Joplin, before deciding what to (re)define by yourself in other places:

  • on Windows: section noteStyle.js of Joplin/resources/app.asar in the folder where Joplin is installed
  • on macOS:

I expect this also gives a clue where to find it on Linux. Maybe there is a way to unpack an ASAR file. That would allow for a more user-friendly view experience. Anyway, it’s a good start for adjustments of the styling in userstyle.css, since the CSS cascade is:

  1. the built-in script noteStyle.js (parametrized, so it adapts to the chosen theme)
  2. ~/.config/joplin-desktop/userstyle.css
  3. links to other CSS files in your notes
  4. hard coded <style> blocks in your notes
  5. hard coded styles= attributes in HTML tags in your notes

Joplin interprets this cascade from 1 to 5, and the last specifications prevail. In the current Joplin architecture, the notes are synchronized, the JavaScript code and CSS files themselves not.


Thanks @memophen. I don't think my knowledge is advanced enough. Don't know where to find the CSS tags :slight_smile:

Ohhh ! New in the latest version of Joplin (1.0.178). In Appearance section in Options, there is two buttons to open userstyle.css and userchrome.css !

Just impressed about development of this app ! Thanks…

For custom style sheet, here is little trick to know all tags styled in Joplin : export notes in HTML and see the source code of the HTML file. Doing this in empty Joplin cause it export all notes without encryption.

1 Like

I quote in Checkbox within table cell - #6 by memophen

as some great progress has been published today

Hi everybody,

please excuse my simplified English, I hope I don’t misuse the language too much.

For the formatting of html documents, I have created a special notebook and a template, without content.
Having followed with interest the “Custom stylesheet” discussion, I would like to apply a custom stylesheet to a notebook and to this template.
I tried various methods, without finding the right one.

First, write all styles in the template
Result: CSS rules are inserted in the note

Insert a link to the particular stylesheet, as

src= "~/.config/joplin-desktop/special.css"
<link rel="stylesheet" type="text/css" href="~/.config/joplin-desktop/special.css">
<link rel="stylesheet" type="text/css" href="/Users/myprofile/.config/joplin-desktop/special.css">

None of them work, I would like how to learn from my mistakes

Note: I have a generic style sheet “userstyle.css” that applies to my other notes. Would it override the specific style sheet?

Hi @betternote unfortunately what you’re trying to do isn’t currently supported in Joplin. If you want a note to have custom CSS you will need to copy and paste the contents of special.css in between style tags for each note.

Thx @CalebJohn.
Now, I know there’s no point in continuing to exhaust myself on this subject.
Applying the model containing special.css remains the simplest solution.

Hi @betternote,

What you try to achieve is perfectly achievable, see here. Supposing that your address is OK, there are two ways to do it:

  @import "/Users/myprofile/.config/joplin-desktop/special.css"


<link rel="stylesheet" type="text/css" href="/Users/myprofile/.config/joplin-desktop/special.css" />

Your <style> block had an invalid syntax, and neither the tilde nor environment variables nor relative (to what?) paths will do the job. The full path must be hard coded.

The imported style sheet will overrule /Users/myprofile/.config/joplin-desktop/userstyle.css, because the last specification always wins.

What I’ve said there about the cascade is not quite correct. The processing sequence is:

  1. the built-in script noteStyle.js (parametrized, so it adapts to the chosen theme)
  2. ~/.config/joplin-desktop/userstyle.css
  3. hard coded <style> blocks and links to other CSS files in your notes, in the order of their presence (their position relative to the real content of the note has no influence)
  4. hard coded styles= attributes in HTML tags in your notes
1 Like

thanks a lot @memophen!
The syntax with @import and hard coded full path works perfectly.


You can also use Help > Toggle development tools from the Joplin menu and:

Click on the element inspector - Marked (1) in the below picture (click to expand)
Point it at the item of interest in the rendered note - (2)
See its full element name in the pop-up - (3)
Look at it in detail in the main tool window - (4)


Oh nice ! With your trick I have been able to find too the good elements name to style the app part that is customized by userchrome.css. Many thanks !

@DominicDesbiens there’s a thread for sharing custom css please consider adding your css to it! I know there are a bunch of us who like to see/borrow/share from others that use Joplin.

Thanks. My css is very personal to my needs, i have to complete it before to share the code.

Just came across this. I’m applying for GSoC under Joplin, and my idea is to implement a framework to sync settings in Joplin. If it works out well, I think it would be helpful to customise styling as a setting and be able to sync it. This would solve the issue of

  1. Losing the styling if it’s stored as a setting
  2. Having the styling notes mess with the UX if it’s stored as a note in a notebook

As I’ve planned it, it would handle the discrepancies in valid settings across platforms, so that aspect of styling should be handled. I’m happy to get feedback on this!

P.S. I’d be willing to work on this even if I’m not selected, if the community thinks its a useful feature!

Hi @anihm136,

I appreciate your enthusiasm. Just some remarks here as an appetizer. :slight_smile:

It's more than a technical challenge, I think. I would like to see some settings synchronized, but not all. For instance, mobile and desktop often demands for different styling. And within the desktop range: the resolution of the screen can certainly make a difference. At this moment I'm forcing myself to keep the settings the same on all my desktops, but once fallen prey to aestheticism, I might decide otherwise. And I don't mind to synchronize the CSS files manually, as I can still oversee my machinery up to now.

So the desirable outcome could be some mixture of global and local components that refer to each other. I haven't done yet any thinking about a configuration for that.

Neither the technical aspect is trivial. How to harmonize desktop and mobile? Especially iOS could be a hard nut, because of Apple's policy.

1 Like