CSS magicians/theme creators — standardisation of theming practices

The challenge is that Obsidian has chosen CSS as its theming language, for better and for worse.

CSS is based on the concept of “cascading” (the C in CSS), which allows you to target a specific element within the application and define its properties.

You can think of it like nesting dolls, containers of containers of containers. If you want to change the color of a bit of text, it is typically 20 elements deep inside of the Obsidian nesting dolls. Some elements are 30-40 elements deep. When a developer wants to target an element, there are virtually infinite ways that they can specify which element they want to target, because there are so many parent nesting dolls to choose from, and you can combine the names of these “dolls” to target an element more specifically.

The way that themes and snippets work are by explicitly overriding what Obsidian’s default app CSS does to an element. So by definition, developers often have to override the specificity (choose a smaller nesting doll) of what Obsidian has already chosen.

By the nature of CSS, this creates a kind of “arms race” of specificity between the default app CSS, theme CSS, plugin CSS, snippet CSS — which is why sometimes developers end up using !important as a shortcut.

Coming back to this statement: “I don’t believe it is possible to standardize CSS across themes and I do not think users should expect snippets to be particularly cross-compatible.”

I don’t mean this in a theoretical way, but in a very practical way.

When you install multiple snippets that affect the same element, there is no way for the snippet to know your intention as far as which one should take precedence over the other. CSS has very rudimentary logic, that is completely hand coded — snippets can’t “know” that other snippets are also active.

The combinatorial possibilities become so rapidly out of hand, that I do not believe it is truly solvable within CSS. Furthermore, it is difficult for these to fail gracefully, because it would be difficult for Obsidian to accurately detect that two snippets could be in conflict.

If you look at most other apps on Mac/PC/iOS/Android these use UI frameworks that make it much harder for this to happen. There is a completely different model of siloing how apps, and components within apps, can affect each other. The downside of this approach is that the bar for developers is much much higher.

Alternatively, Obsidian team could build a special compiler for themes/snippets that heavily restricts which combination of selectors themes can touch. However, this would severely affect the creativity theme developers can have, and the compiler itself would be a lot of work for Obsidian team to build.

Personally I think Obsidian team have made the right choice with CSS, because it offers so much freedom. But with flexibility comes this tradeoff.

I love Obsidian’s modularity, and I believe it should still be an important goal for the app. But that modularity can be accomplished more easily through plugins. Unlike themes/snippets, plugins can be smart about knowing the state of the app and what other plugins are active. The modularity of cosmetic changes is much harder to achieve within the constraints of CSS.

3 Likes

I think this is an interesting point that is worth generalizing to the entire user base. I’d like to add one more category which I suspect describes at least 30-50% of the user base.

  1. People who use the default theme
  2. People who use a community theme and make basic changes via Style Settings, and other plugins
  3. People who use a community theme and heavily modify it via snippets and/or editing CSS
  4. People who create their own theme

I would be curious to know what proportion fits into each category.

What is interesting is that 3 and 4 are virtually not possible with most other apps that Obsidian users are coming from (Evernote, Apple Notes, Bear, Notion, etc) — and the ones that do (Logseq, Roam) have solved it the same way as Obsidian, via CSS.

5 Likes

This is a great way of putting it! Users with snippets have to pick smaller/the right nesting dolls, which is hard when you’re learning and which contributes to the problem as well.

I can tell the issue is a hard one, and I didn’t mean my point above as criticism. I’m mostly hoping the combination of the skills from multiple wizards could help make the problem more manageable for less experienced users. I’m definitely not in the majority, I think going for your own theme is rather a rare case.

We could design a small survey if insights into these splits inform the decisions on how to best tackle the CSS workflows.

A few other uses/ideas of the snippet store that I could see:

  • A centralized repo with snippets working independently on top of the default theme, which theme designers can contribute to. It could be forked by theme designers and adapted for X theme (adjusting specificity, variables, whatever). Designers could choose which snippets to support and give clear indications of what is in scope and isn’t.
  • Usable as a reference for frequent requests by users, giving a minimum working example, and which could be used together with the theme/dev vault.
  • Perhaps collaboration and attribution of “modular theme parts” usable by other themes?
  • An easier way to document how to change specific types of snippets for a particular theme, e.g. “themes in these folders need X changes in specificity”
  • Basis for common-shared styling plugins?

Snippets that could be plugins (based on what I see on appearance and the forum):

  • changing default fonts (UI, headers, text) → Advanced appearance does it, but not all themes follow this convention in my experience
  • changing colour or “formatting” of different elements in the Markdown syntax → see above
  • tags (and this is a personal gripe of mine)
  • file tree → there are a couple of plugins that do icon stuff, not sure how well integrated they are with themes or if there is a CSS gap they could fit there

Finally, we might want to collect a list of those plugins that have abstracted some of the snippets for theme designers. This is the closest note we have int the hub Theme settings plugins - Obsidian Hub - Obsidian Publish

6 Likes

I’m a user who doesn’t know CSS at all.
(I have learned a tiny bit to achieve occasional effects in padding, by adding snippets).
Sometimes I use Default, but it is always too contrasty for my eyes.
Sometimes I use community themes. Always chosen for colour palette. Avoiding looks I know (now) I dislike.
Switching themes whenever I hit undesired behaviour.

I have no desire to restrict theme designers.
My biggest gripe is that I rarely know what I’m getting into when I load a theme. Or how recently it was updated and whether it works with LP or not.

I’d really prefer a more useful set of filters and queries. Dark/light is not enough, especially when many themes are somewhere between the two and some have subverted the switch for other purposes.

2 Likes

I agree with a lot @kepano says; just to give the non-theme-developers an example why standardization & versatility are a bit of a trade-off: To make a plugin that would change background colors for all themes, it would require all themes to implement colors in pretty much the same way. The features of some themes, however, would not be possible then:

  • some themes like Prism achieve their distinctive look by changing how backgrounds colors relate to each other
  • some theme features like the sliders to adjust brightness in my theme only work by overriding pretty much everything regarding background colors

To make those themes compatible with a background-color-plugin would require even more complicated solutions by the theme devs, or would require theme devs to forego such features.


I think there is a certain agreement that some theme features should be “centralized”, either via a CSS snippet or via a plugin. This wouldn’t just be great for the users, but also the people interested in creating themes, since they wouldn’t have to implement dozens of common features (that are sometimes not trivial), to be on par with the bigger themes who already implemented many of them. Hence, feature-centralization could help smaller or newer themes to “catch up” more quickly, which would benefit the overall diversity of themes.

While I tend to agree with @kepano, that plugin are the better way to do so than snippets, I do fear that centralizing features via plugins also wouldn’t be as easily done as said. The biggest challenge I see is that such “theme feature plugins” would have to be developed by people who know their way around CSS and plugin development. While our community has many great plugin developers and theme designers, I think I can count the number of people competent enough in both areas with one hand. (Of the top of my head: @kepano, @NothingIsLost, @death_au, @javalent, and @mgmeyers). And I don’t know how much time those people have to develop & maintain a couple of dozen “theme feature plugins”, especially considering that all of them maintain multiple plugins/themes already.

5 Likes

I agree with this wholeheartedly. It would be very helpful if themes could be versioned and updated like plugins, and if the theme changelog and readme could be visible within the app.

4 Likes

There are a lot of really great points being made in this topic.

I believe that the number of people this issue affects is small (less than 1 or 2% of users), however I do think the people running into this are some of the community’s best patrons, power users, and contributors. Minimal theme has been downloaded ~40K times in the past 6 months, but I’ve only heard of this issue from around 50 users. I don’t mean to minimize the problem, but it influences what approach should be taken.

IMO a solution that relies on soft guidelines or collaboration is not viable. A real solution would require enforcement through code (like a compiler), or through strict guidelines that would cause a theme/snippet to be rejected (both of which seem like a lot of work for Obsidian team). The reason soft solutions won’t have much effect is that as the number of plugins/themes/snippets grows, it isn’t realistic for every developer to collaborate with every other developer to make sure everything is compatible. And if there isn’t a compiler or hard rule to stop you submitting your code, then we’re back to where we are now.

Another option that we have not discussed is making CSS customization more approachable. CSS can be tricky, but the necessary basics are within reach of more people than we give them credit for.

The most common type of request I see is for small changes that are actually extremely easy to solve via CSS — often a 1 line change… e.g. change line height of text, spacing between bullets, color of bold text, etc. If I added an option for every request of this type, Minimal’s Style Settings menu would be trying to replicate everything CSS itself can do.

The Obsidian community has some of the smartest and kindest people I have interacted with online. Obsidian users are also some of the fastest learners, and most tenacious explorers of complicated new workflows and ideas.

This leads me to wonder if it would be easier to solve this problem by providing more resources to help this 1-2% of users learn how to make or edit a snippet themselves. This could unlock much more creative potential than other options we’ve discussed.

6 Likes

I agree. to a certain degree, we have already started to collect guides and resources for exactly that in the hub: for Theme Designers - Obsidian Publish

I think two things that would help a lot of people are a (video) guide on how to use the console and one regarding specificity. While there are guides for both out there, I feel like it’s often a whole different thing to use them for styling Obsidian (web developers do not need to reach crazy high specificity like you have to do when styling certain things in Obsidian, for example.)

3 Likes

I agree with the majority of points made here.
Just summing up some points being discussed, and maybe adding my 2 cents:

  • using plugins, rather than snippets, for adding popular and highly requested features would be a better way of implementing them, since plugins provide more control and granularity, and snippets can be very unpredictable
  • a snippet store could be useful for centralizing CSS snippets (especially simple ones), as well as serve as a good entry point for people who want to get started into customization, or are simply looking for something slightly different from default
  • the existence of a way to better display themes – by versioning them, adding changelogs, filtering, etc – would be a good way for users to know what kind of experience they’re getting before applying the theme and potentially coming across something unexpected, wasting their time. I think there used to be a button to try out themes before downloading them (I might be wrong), but it would complement this nicely
  • distinguishing between colour schemes and themes could be a useful filter
  • in order to foster a more diverse theming community, the creation of straightforward guides and templates for CSS could prove to be even more fruitful than trying to achieve some sort of general syntax/workflow consensus.

I think adding more support for theming, like adding Style Settings as a core plugin, could prove to be a good way to add customization to the default app, since it doesn’t necessarily enforce specific customization norms, but allows for modularity in a very smart way, I feel.

Also, I believe the app itself still has some work to be done regarding providing a good, consistent experience from the get-go. I can’t be sure on this, but I think there might be a good number of users switching to custom themes because of the somewhat low standard of the default theme. There’s a difference between looking for a different experience, and simply looking for an experience. By no means do I want to bash on the default theme. It is understandable given the size of the team and the amount of features and overall work that gets done each week, but I feel like it’s something that hasn’t yet been talked about, and might deserve a mention at the least.

8 Likes

I think this is an excellent recap, and I agree with 99% of this. The last point is also important, I agree that the default theme needs some love.

My only concern with your recap is that I think a snippet store will create more problems than it solves, but I seem to be in the minority here. If a snippet store is added I think it should be gated behind “Safe mode” like plugins, because here be dragons.

6 Likes

I agree! Although I think it would be a good way of centralizing snippets, I can also see it still being a headache if/when snippets get outdated, for example. And I’m sure we as theme developers would still be asked to add compatibility or some version of them to our themes. For the people who just want simple things, though, I reckon it’d be easier to have a centralized place for those kinds of snippets to not overwhelm the forums/discord with similar requests for finding x snippet.

PS: An option to “pull the plug” on snippets would for sure be required, imo

2 Likes

Here are my thoughts on some key points being brought up:

Standardisation Across Themes

My Opinion

“I don’t believe it is possible to standardize CSS across themes” - No matter how I look at it there is no way around it with the nature of CSS.

“Features should probably be centralized via plugin” - I would find this to be ideal personally but it’s a big ask for Plugin Developers. I’m all for people experimenting and seeing what catches on with users with their Theme’s pure CSS implementation of features but the moment users start expecting it from other themes, it becomes an issue. I feel like there could be an effort made to help bring those ideas on as Plugins, as long as there is an individual willing to maintain it, or even pitch them as core Obsidian features.

Time intensity and difficulty of constant maintenance is something I struggle with. Despite the fact that people in this community easily being one of the most supportive I’ve ever encountered, I feel like contributing to a theme with ideas/feature requests, although a good indicator of interest for the Developer, can be a big ask depending on the Theme’s state and feature complexity. It is very hard to contribute Pull Requests for anyone willing to try and help out; even if you are well versed in CSS. Hence why, including myself, people chose to roll their own theme somewhat further adding to potential fragmentation and problems down the line.

Obsidian has already become a kitchen sink of tools, workflows and users. Understandably so! It’s a fantastic tool with a lot of freedom to do what you want with it. No wonder so many users from all types of software have migrated to it. Sadly in my opinion it’s suffering from it’s own success. Constant community effort to try and pull new functionality out of it by building up new Plugins, Themes, etc. do sort off contribute to the difficulty of maintaining it by Community Developers and I’m sure core Obsidian developers as well.

I also don’t see a Snippet Store be a viable feature besides very basic snippets specifically made to go hand in hand with the default theme only. The ever increasing speed of Obsidian’s evolution and development made by the Community already provides enough work for all Developers and this would just become yet another thing for people to complain about and developers to pour hours into supporting.

Lastly, the issue of maintaining the Legacy Editor modes. I would like to have a set timeframe for when it is planned to be dropped. It’s still a fresh change so some time to process this is definitely required. Everyone trying to maintain it in their Themes/Plugins will only amount to it taking longer for users to transition if the expectation is set that Developers will keep it going. Theming 5 separate modes is a lot to maintain and will only become more work to rip out once it’s deprecated.

Actionable Items

  • Create a resource which can be referred to when trying to tame the expectation of some users when it comes to support of features in Community Themes.
  • If a Snippet Store is created, just as @kepano pointed out, it should be gated behind Safe mode or some other clear separation to indicate to users that they can’t expect Community Themes and possibly even Community Plugins to play along nicely.
  • Timeframe for Legacy Editor’s EOL.

The Community Theme Store Needs Improvement

My Opinion

The current state of the Community Theme Store is far too basic for the utility they provide. It lacks the depth which the Community Plugins Store provides with short explanation in the Sidebar list and a whole Readme going into detail once selected. A name and a screenshot isn’t enough anymore when each theme offers unique features, might have plugin requirements, offer specific plugin support, etc.

Some way of indicating support for Community Plugins and tagging the availability of commonly demanded features from users would be nice.

I think it would be smart to have a distinction between Colour Schemes and Comprehensive Overhaul themes.

Actionable Items

  • Redesign the Community Theme Store to behave and look like the Community Plugins Store or another more information rich design.
  • Work out what the ‘requirements’ are for a Theme to fall under a Colour Scheme or Comprehensive Overhaul Theme.

Community Knowledge Centralisation (Slightly off-topic but I think still relevant)

My Opinion

Community brainpower and knowledge should have a centralised place to focus it all into. In my opinion the Obsidian Hub is the ideal place for this. The speed of progress is extremely hard to follow unless you are a dedicated Discord/Forum reader. I have no idea how @EleanorKonik manages to stay on top of it all and produce the Obsidian Roundup.

Where possible, I think we should help each other in avoiding the common pitfalls. For me one of those was not using SASS from the start and documenting my code better; now it’s a big task to rework it and make it as maintainable as possible. Obviously this might not be the case for everyone and just plain CSS will be enough for them but I’m sure this will resonate with some.

In turn this has motivated me to work on a guide for the Obsidian Hub to help others avoid this and have a better time starting out as Theme Developers or for existing Developers. It will be there for those that are interested but by no means an enforced way of doing things. Again I don’t expect everyone to do the same even if they would like to due to the time it takes to do.

Assisting each other with guides, shared knowledge and creating more opportunities to do so with e.g. events (such as Obsidian October), workshops, weekly/monthly meetups (voice calls or chat) where we focus on discussing one specific topic is what I’d like to see more of. Maybe a separate section of the Obsidian Discord or Obsidian Community Talks would be ideal for this; Would prefer to avoid making another Discord server to not fragment further and avoid ‘echo chamber’ effect.

Discord is already a lot to parse through and there is also the forum. A lot of questions and answers, valuable information and in depth discussions get lost (on Discord specifically) but they happen there due to convenience of a live chat as opposed to the forum imo. I’d love to have community process to assist in documenting them.

Actionable Items

Think of a workflow for the Community Ideas to become Community Knowledge. e.g.
1. Pull out good ideas brought up in the Forum/Discord .
2. Create a thread on Discord or a Meta post on the Forum to further discuss the idea.
3. If it becomes something great, work on dedicating some time for a meetup/discussion panel to develop on it and work out Actionable Items from it.
4. Produce content about the idea which is easily accessible by the community (Obsidian Hub for Guides and Information, Plugins/Theme Enhancements available in the Obsidian Community stores, video tutorials from YouTube creators, etc.)


P.S. Hopefully none of this comes across in a negative or too demanding way. I just feel like there are clear areas that could do with improving, albeit I’m not super confident in the exact ways to achieve said improvements. There might be other, better Actionable Items some of you can pull from what I said hence why I chose to share my thoughts.

Also sorry for a wall of text :sweat_smile:

22 Likes

I don’t have particularly much to add given that I agree with most ideas here, even conflicting ones.

Some random thoughts:

  1. I agree that the legacy editor should be deprecated in a timely manner as a matter of preventing further path dependency and the increasing complexity of the already-currently-complex themes.
  2. Community Theme Store should indeed look more like the Community Plugins Store — in fact, it is for the exact reasons and consideration @Damikiller37 has mentioned that I suggested the plugin store layout for my Snippet Store feature request.
    2a. It would also be helpful if themes can have tags implemented, which would not only pinpoint to dark/light themes but also allow themes to be mentioned if they supported LP or not, amongst other things. This would solve @Dor’s concerns.
  3. A Snippet Store that would work superficially somewhat like the current Style Settings Plugin work (but hopefully through a solution that wouldn’t need additional code in the CSS file, totally unlike Style Settings) might be a viable idea, considering the minority of the theme developers’ opinions here towards true modularity, whilst allowing a certain level of customisability. It might be helpful to some if there is an option for some theme developers not to support a Snippet Store, somewhat like how Style Settings only work if there is code in the CSS file supports it.
    3a. Tags might prove useful, here, as well, as with point 2.
    3b. Whilst I can understand why theme developers might not like a snippet store, snippets inherently are one part of Obsidian’s way of managing appearances. On that note, I honestly do hope there is less hostility overall towards snippets.

In my opinion, I perceive @argentum’s and @kepano’s classifications are comparably similar, but materially different. Kepano’s classification lends strictly to the ability of said user to create/modify the theme; whereas Argentum’s classification deals somewhat more with the satisfaction of said user with themes. There are people who are perfectly fine with using other themes, but create a theme for other purposes in mind (Chetachi’s Yin and Yang comes to thought, which I remember was created more with her sister in mind). There are way more people who are not as ably adept as Chetachi, but are not necessarily entirely satisfied with the current options. I do not claim to know the numbers or percentages in this cohort, but considering the number of people downloading custom themes (and asking how to do X, Y or Z in Discord and the forums) — I do not believe this number is insignificant. Which is also partially the reason why this conversation needs to be had in the first place.

  1. For what it’s worth, this discussion has revealed to me that 1) there are relatively high levels of ‘feature creep’ in themes; and 2) the Obsidian ecosystem remains inherently fragile given the multiple ‘single points of failure’ which has arisen precisely because of Obsidian’s innate customisability. And I mean in terms of plugins, themes, and even our shared knowledge.
    5a. Feature creep (themes doing ‘more’ than it should): there has been suggestions here that plugins would be a good way to do certain things, instead of having things styled via CSS (be it via theme or via snippets). I agree with the general gist of this. But as @pseudometa pointed out, the intersection of the Venn diagram between plugin developers and theme designers is rather small. So, the mission creep in the first place derives from plugin developers mostly =/= theme designers, and I don’t see how plugin-related solutions might solve the issue unless it’s something the [plugin developers ⋂ theme designers] group would like to tackle.
    5b. This is slightly off-topic, but going back to one of @Damikiller37’s main points (and something @Dor has mentioned in other thread before): what can we do as a community to make the entire experience less frictionless and painless (and hopefully less ‘tech’-y), for people who would like to edit their current themes, use Dataview and Templater without always deferring to Discord, and how, as a community, can we ensure that relatively important plugins (that might slowly become central to someone’s workflow via mission/feature creep) are not orphaned and abandoned?
3 Likes

I am not sure how standardization would work. Apart from the obvious question “who is the standards authority and how do they go about the job”, there’s the reality that CSS is a messy thing and it is very hard to rein it in in ways that everyone can agree with.

As a user of the themes – many many thanks to anyone who develops one for the community – I am concerned about making the appearance of my Obsidian vaults as pleasant and workable as possible. I struggle at times with the many appearance-related features in both the core and community plugins, the themes themselves, snippets, etc. The developer view is daunting and messy, and shouldn’t be where users are sent to figure our simple questions like “how do I make my headings smaller”.

I would love to see a plugin or tool that let me compare themes side-by-side – using my real data – without committing to them. Or a tool, perhaps the same tool, that let me tweak appearance elements like colors and fonts without having to go through the arcane processes of figuring out which CSS elements do what, and how the core CSS and theme CSS and snippet CSS elements are contesting with one another.

In other words – it’s not so much about standardization, IMO, because that will never work, but about making simpler and user-friendly the wonderful flexibility Obsidian offers in customizing appearance. Users today are, I think, confronted with the need to be technically oriented in order to understand how to adjust appearance.

7 Likes

I’ve already talked in the #appearance channel about how I was reduced to tears after literal (6+) hours of trying to fix CSS because I value a particular color scheme but the themes that currently provide that scheme are “out of date” & don’t provide css for LP or Mobile.

I recognize that I’m totally not a normal use case, and I really appreciate the wonderful response by @pseudometa and others to make a template theme for the hub so I can just make my own theme finally, but I’m definitely in favor of some sort of light standardization—mostly with snippets and having some sort of snippet repository that I can know is up to date and will work with the default theme. Because I don’t know CSS, just having examples where I can tweak a default or template goes such a long way and makes it easier to quit or ask for help when clearly something I am doing is not working. For example, a couple of weeks ago I spent 2 hours trying to stylize unresolved links. the whole time I was editing a script meant for legacy source mode and it never worked for LP (obviously) so I ended up very frusturated. I think the current situation of having like 10 different GitHub repos with css scripts on them would be really helped by centralization. I

5 Likes

This isn’t a complete solve, but I was inspired by this thread to re-architect Minimal 4.4. The theme has been split into partials with files for each feature and plugin it supports. The code compiled and minified using Grunt, which could allow additional checks to be run in the future. I tried to create a folder structure that is as clean as possible to help people navigate what is essentially a collection of around 80 snippets that come together to make Minimal.

You can read more at the bottom of the release notes:

11 Likes

On the topic of time intensity and difficulty being a barrier to entry, it could be worth seriously considering integrating a donation button directly into themes and plug-ins.
This, with the centralization you’re proposing, could help motivate creators a lot to continue required maintenance on their work. It also could fund the Obsidian team if they wanted to take a small portion of each transaction.

1 Like

A lot of Theme Developers already include ways of supporting them through their Github Repository (in the Readme and/or Sidebar) and some, off the top of my head @kepano, include a link at the bottom of their Style Settings. Personally I feel like the monetisation portion of Theme Development is a little tricky since no one wants to come off as though they are expecting users to pay them for their work. Would it be nice? Sure. As mentioned it takes a lot of time to maintain themes, but by no means should it be expected in my opinion. I feel like for most Theme Developers it’s just a way to give back to a great community and to have a project to work away at.

If the Community Theme Store gets reworked, then an option to add a donation link for your theme could be an option. But that is entirely up to Obsidian developers.

With a stronger push for monetary support, there would be greater expectations out of Theme Developers and not all have dedicated time to work on their themes but only portions of the day/week to chip away at it.

As for splitting donations between Theme Developers and Obsidian Developers, I personally don’t feel like the amount of money being donated at the moment is significant enough for it to be something that is worth considered at the moment. Also there are already multiple ways of supporting the development of Obsidian directly with Sync, Publish, Catalyst, Commercial Licences, etc.

I have read this thread and being a regular user in the category use community theme and style with Style Plugin I have almost no experience/knowledge of CSS.

I have 2 CSS snippets active:

  • header.css (to make all headers h1 … h6 a different color, I like colorfull themes)
  • frontmatter.css (to hide frontmatter in read view)

I would suggest to create CM5 versions of themes and build further with CM6 theme versions. Using the legacy old editor is a choice people make. By doing that they accept to not have all the features CM6 gives you. The same reasoning can be applied to themes. CM5 editor is current version of theme. When you use the new CM6 editor you get all the bells-and-whistles.

Just a user’s opinion ;-

Regards,
Jeroen