Community Project: Modular CSS Theme

Plugins and Custom CSS CSS
#1

There are almost no themes for RemNote (ethomasv/RemNoteTheme being the exception). Some people would like to make a theme if they knew it would not break for a resonably long time. This probably will not happen for at least a few month.

I think the best approach for us as a community would be to focus on a modular theme template first which abstracts away all the possibly changing/breaking markup details and expose CSS variables which can be kept stable over time. The implementation of an actual theme is then reduced to a one time definition of those variables.

Modular Theme

Roam has already done this

Basically it looks like this:

/* Hidden implementation (theme template)*/
.highlight-color--red {
  background-color: var(--highlight-color-red, red);
  border-radius: var(--highlight-border-radius, 0px);
}
.highlight-color--yellow {
  background-color: var(--highlight-color-yellow, yellow);
  border-radius: var(--highlight-border-radius, 0px);
}
/* ... */

/* Exposed Customization (the theme)*/
:root {
  --highlight-color-red: red;
  --highlight-color-yellow: yellow;
/* ... */
  
  --highlight-border-radius: 3px;
/* ... */
}

Advantages

A modular theme has a few advantages over independent themes.

(1) The maintenance efforts for fixing themes when markup changes happen are centralized and can be done by very few people. They are then distributed to all themes based on the template automatically. This means the maintenance effort for themes is zero. The creation time of theme is also quite low, more in the order of minutes to 1-2 hours as opposed to multiple evenings.

(2) Such a template could be implemented iteratively starting with the most valuable things, e.g. abstracting highlight colors and some fonts. And only later (aka when there are more devs) do spacing stuff etc.

(3) Maybe most importantly: Theme creation would be much more accessible! The modular template is self descriptive and even non-programmers can change the values of some well documented variables and see the effects in real time.

(4) This is a great community project: The maintenance effort/responsibilities can be distributed cleanly over multiple people. Coordination should not be too hard. There are easier parts (e.g. colors of various UI elements) and harder parts (thinking about abstracting spacings). Everyone can contribute in a meaningful way.

Such a thing could (but does not has to) be distributed over the Library. The architecture to define nicely nested code blocks with embedded documentation and examples and the split of implementation and customization is already in place.
Even an (auto) update mechanism is prepared and could probably be made functional in 1-2 days of work.

Next steps

The first steps are easy and non-technical:

  1. Identify the most important parts that a theme would like to change (Highlight colors, background color, font-family, …)

  2. Categorize and systematically name those variables. The builtin Custom CSS template is a good start and we could reuse much of the previously mentioned roam template, both in terms of exposed variables and accessible structuring/documentation.

Maybe we should draft this in a collaborative document somewhere? This would be step 0.

Anyone willing to set this up?

(Unnecessary Cynical Comment)

I mean on a level the library itself is such a modular theme where each scroll captures an aspect of the interface which can be maintained and customized separately. The only difference is that it can not be installed as a complete package - yet! It has still not generated any momentum and people are still not inclined to pool efforts so :man_shrugging: I still have hope though, feel free to prove me wrong :smile:

If we have this we can assign responsibilities for different areas and implement the actual CSS.

References

@Martin I had the impression that the Roam modular theme reuses CSS variables defined by Roam itself. Does RemNote internally use variables and if so, could they be exposed?

12 Likes
Calling all devs in the Community 📢
#2

The rapid change has indeed put me off from working on themes but also because the default themes got much better awhile back with one of the updates. I’m just trying to envision how this would work. Is it something like this?:

  1. I would go to this proposed document, copy the snippets for the CSS variables, then paste it into the stylesheet for my theme.
  2. I would then also copy/paste the associated snippets for the CSS selectors into my stylesheet
  3. I would then tweak the variables in my stylesheet to create my specific theme
  4. An update comes along, breaks a part of my theme (and everyone else’s too)
  5. I (or someone else) notices that the problem is caused by, say, a change in the naming of a CSS selector. We would then append the document you are proposing to use the new selector name.
  6. We all now copy/paste this updated selector snippet into our stylesheets to append the broken section
  7. Another update comes along, this time with some cool new feature
  8. We append our proposed document to include variables and selector snippets for the new feature
  9. We copy/paste all these new snippets into our stylesheets and tweak the variables to fit our theme
    10 Repeat steps 4-9
3 Likes
#3

Just to be sure there is no missunderstanding: The document I proposed is to only initially plan and coordinate the project. The Modular Theme Template itself would be a set of version controlled .css files plus some documentation/examples bundled together to something that can be inserted into RemNote’s Custom CSS page. (e.g. look at this definition: https://github.com/hannesfrank/remnote-css-rem-types/blob/master/manifest.json)

The Theme development and optional end user customization would look approximately like this, but having an outline covering every aspect of the interface (highlights, fonts, sidebar, … and not just Divider):

Note the Code section (the Modular Theme Template) is hidden and not interesting for theme developers. (Compare to the result of above manifest: https://hannesfrank.github.io/remnote-library/#/scroll/com.github.hannesfrank.remnote-css-rem-types). Also you would probably not have a Code section in each part of the outline but only a single large one which is easier to update (see below).

So to summarize:

The system has multiple parts:

  • The Modular Theme Template: A set of CSS selectors + rules abstracting away all markup and only exposing a set of CSS variables. (The whole outline above, where the abstraction lives in the Code section.)
  • A Theme: An assignment of the values for (a subset of) the exposed variables. (The Customization section above.)
  • An end user Theme Installation: If the end user does want to further customize the theme you could bundle Code and Customization to a single .css file. Otherwise just paste the same theme outline again.

There are 3 groups of people:

  • Modular Theme Template maintainers (1-5 people): These guys fix problems when the markup changes and figure out more variables and abstractions which Theme developers can use.
  • Theme developers (1 for each Theme): These guys use the Modular Theme Template to create Themes by essentially define variables. This project is aimed at making their lives easier since once a theme is created it should not require any more mainenance.
  • End users: These guys install a Theme they like. Optionally they can further customize it by overwriting some variables again. For them it does not make a difference to use a theme built from scratch or one based on the modular template.

What you describe is basically the workflow for theme developers. But I hope there will be no or less complicated copy&pasting for both theme developers and end users:
The Modular Theme Template should “push” updates more or less automatically to all theme installations. You could for example @import(http://github.io/path/to/theme-template.css) but this would require being online. It is also possible to push the changes using the backend API directly into the Custom CSS page.
The idea and whole point of this project is that a theme does not need to be touched again after it is developed.

So instead of 10 steps its more like:

  1. Go to RemNote Library, copy a theme (based on the Modular Theme Template) and paste it into Custom CSS.
  2. Overwrite some variables to further customize. (Optional for end users)
  3. If you are a theme developer: Publish the theme.

One problem you raised is how to get the a theme out of RemNote for publishing after it is developed there. Roam’s modular CSS does this by copy&pasting form the published Roam graph or importing the exported JSON. Both of those might not work for RemNote yet. But I’m pretty confident that we could build something easy to use for that too: For example you can automatically (aka by a build process) replace all code blocks with @imports(http://localhost...) and use a DevTools Overwrite to sync the code.

3 Likes
#4

Is the modular CSS theme something you still need help with? I am frustrated by the lack of themes and there needs to be a standard! I have very informal experience with CSS, just tooling around on my own for the past few years, but I want to help. Please send me a message here if so, thanks!

#5

Actually we got a few new themes lately. I liked them in https://github.com/hannesfrank/awesome-remnote#themes. The one by eustachio is pretty innovative regarding how portals are styled. And JoshKioro’s is quite configurable and could therefore be used as a basic theme template already.

Help is always welcome!

The current state is the following:

  • Silent (I don’t know if he has a forum account, but he is on Discord) has made a MVP where you can configure basic colors and fonts already!
  • I was trying out a templating engine to automatically piece together all source files in the repo to copy&pastable markdown and also generate a version with @imports(http://localhost...) to live reload when editing the CSS and sync from DevTools to the files as well. These changes are still WIP and not pushed to Github yet.

That’s totally fine! I think there is still plenty of stuff to do. You can pick any (independent) UI element of RemNote, think about in which ways people would like to configure them, capture these options into variables and write some CSS using those variables. When you have something, make a PR on Github and we’ll see how we can best merge it. (Or post here if you don’t know how to do that yet.) The hardest part is finding some good and consistent names for the variables I think and where to sort it into the template hierarchy :wink: But we can discuss this in the PR and rename if required.

Some small, independent components to style are:

  • rem references (color, :before and :after text, font style, border?)
  • tag buttons (font size, border and border radius, background and font color)
  • hyperlinks
  • clozes
  • rem with powerups?
    • todos
    • extra card detail

Have a look on how the MVP handles the highlight colors. You can also get some inspiration from the Roam version linked above or extract something you like from another theme.

#6

In the Remnote Article on the Light Theme, the screen shows show the text highlights as curved instead of rectangular - how is this achieved? Thanks!

image
image1780Ă—776 177 KB

#7

In CSS this can be achieved with something like:

border-radius: 16px;

Maybe add some padding too:

.highlight-color--green {
border-radius: 20px;
padding: 2px 8px 2px 8px;
}

Not sure if there’s a way to make it for all colors at once

1 Like
#8

That’s great - many thanks!