Custom stylesheets

I actually think a convention of something like a notebook named Joplin config with notes inside called Markdown rendering styles and Joplin app styles would be quite elegant (or userstyle.css and userchrome.css to be consistent). I might just be biased from GitHub’s approach, but I like it when content and config are stored in the same way.

I could see this implemented along a spectrum of name customization:

  1. On one extreme, we could just say “The folder must be named X, and the files must be named Y and Z”. This would likely minimize confusion down the line, because then everyone has files with the same name. This would make it harder for people to make mistakes, and support questions will be easier to phrase properly rather than having a dance where we try to figure out what folks are talking about.
  2. On the other extreme, the folder and file names could be totally customizable. We let folks determine their names in Settings, similar to how they can set their text editor. This would entail 3 new fields: Configuration notebook, Markdown rendering styles, and Joplin app styles (or some other names).

I don’t recommend creating a complex abstraction on top of these files, like hiding them or anything like that. I think that makes it much more likely that folks get confused, forgetting that it’s even there. If it gets annoying to see this config notebook in the sidebar, here are two suggested solutions that I think would create less confusion:

  • Right now, when I have an old notebook I don’t use much anymore, I just nest it under a meta notebook called Archive, which lets me minimize all of the sub-notebooks. This takes up less visual space than having lots of old notebooks lying around, without making it easy to forget they even exist. (The problem is this might break the config notebook because I guess now the notebook name would be nested? I think it’d be fine, but worth checking)
  • Perhaps we could create some more formal concept of archival, rather than having to nest it into a meta notebook.

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!