UX feedback on the current theming workflow in 0.101.x

[pyz0123-cpu]

I’ve been experimenting with custom theming in 0.101.x, and while the internal model is powerful, the current workflow for applying CSS feels surprisingly elaborate for something as simple as changing UI colors.

Here’s what the process looks like today:
create a new note
add the appCss=true attribute so Trilium treats it as code
write the CSS directly inside the note body
add hidden=true so it doesn’t clutter the tree
remember the exact note name so I can find it again via global search
reopen it through search whenever I need to edit it

All of this does work, but it’s a lot of internal knowledge and several non‑obvious steps just to adjust a color or two. The workflow ends up feeling more complex than the task it’s trying to accomplish. A more streamlined or discoverable theming experience — perhaps a dedicated theme section or a clearer UI for managing CSS notes — would make this much more approachable for new users. Unless I am missing something - this seem a little bit much just to change a color.

I really appreciate the flexibility of the system and the direction Trilium is heading. I’m sharing this in the hope that it helps refine the UX around theming as the project evolves.

[hulmgulm]

Why not have a note called Trilium in your tree and have all the theming, custom widgets, and scripts located there? Why hide it?

[pyz0123-cpu]

That’s a valid approach, but I prefer to keep configuration separate from my content. Hidden notes work well for that — the issue isn’t the concept, it’s the number of steps required to create, configure, hide, and later rediscover a CSS note. I’m hoping for a smoother workflow in future versions.

[eliandoran]

@pyz0123-cpu , if you could draft a UX workflow, we can consider it.

However please be aware that theming is by itself a complicated process. If creating a note and selecting the right code type and attribute is a chore, then developing the theme itself using CSS selectors far outweighs the complexity if you ask me.

If you were thinking more like for end users, theme developers can share the .zip of the theme which makes importing it already so much easier (disable safe import and move somewhere).

I've given thought in the past of having fixed locations for themes, scripts, but it would break the core principle of Trilium where themes, scripts can be freely placed.

However, there are some things to consider:

1. We are planning to have a plugin system which will indeed handle the note creation on its own, so if you were concerned by the end-user this would be the way to go. However, for developers the process of creating a plugin would actually be more complex than what we have now (have to create a manifest first).
2. If you're simply looking to have, say a settings page, which lists all the active scripts and themes (but without ability to create theme), it can be done. We just have to think of the UX.
3. If you find yourself creating many widgets, scripts or even themes or custom styles, you can create a template which will already simply the process quite a bit. We can consider making them system templates (available by default), but not all users would benefit from this.

[pyz0123-cpu]

Thanks for the thoughtful reply — and I want to be clear that I’m not trying to create extra work for anyone. My goal is simply to make the workflow of creating a theme easier and more discover-able.

Right now, the process works, but it’s surprisingly elaborate for something as simple as changing UI colors. The number of steps makes it feel almost unbearable for new users:

create a new note
change it to code
add the appCss=true attribute
add hidden=true so it doesn’t clutter the tree
add excludeFromExport=true so it doesn’t pollute exports
write CSS directly in the note body
remember the exact note name so I can find it later via search
unhide it manually to edit it
re‑hide it afterward

This is a lot of internal knowledge and a lot of steps just to begin theming.

In an ideal world, sure — a settings page with color pickers (like Windows display settings) would make theme-ing extremely approachable. But I also understand that everyone would want their own custom theme, and that quickly becomes a huge feature set. So I’m not asking for a full visual theme editor.

What I’m really hoping for is a smoother path for users who do want to write their own CSS.

Proposed streamlined workflow - a simple “Create Theme” action in the Appearance/Options area

this automatically creates a code note with the correct attributes (appCss, hidden, excludeFromExport)
the user is taken directly to the note body to write CSS
a “Manage Themes” page lists all active theme notes (no need to unhide or search)

This keeps Trilium’s philosophy intact — themes and scripts can still live anywhere — but removes the multi‑step ritual of creating, configuring, hiding, and rediscovering theme notes.

A small UX layer on top of the existing system would make a big difference without changing the underlying architecture.

This is just one approach — there could be others that are easier or better, and I’m completely open to refining this one if needed.

[adoriandoran]

We are planning to offer a ready-to-use custom theme CSS template that you can download and import into your Trilium instance, where you’ll find the common CSS variables for customizing theme colors. But there is still some work left to do on theming before the CSS variables become definitive.

[pyz0123-cpu]

Thanks for this discussion. Today I tried to add the #hidden attribute and it did not work. I also tried #hidden=true. Still no luck. Am I missing something? Is there a reason these do not work anymore?

[eliandoran]

@pyz0123-cpu , there's no #hidden attribute built-in Trilium.
Perhaps you're looking for archived notes? You could also move your notes in the hidden subtree.

Where did you find a reference to #hidden?

[pyz0123-cpu]

Sorry — my bad. I assumed (incorrectly) that because #hidden was accepted by the Attributes panel, it was a valid attribute. Nothing in the UI indicated otherwise, so the only way to discover it wasn’t real was to add it and see that it didn’t work. That part is on me.

However — at one time there was a functional, though undocumented, hidden = true, key/value attribute that did hide notes. That internal flag no longer works in current builds.

So the real question is: Is there a reason why a user cannot hide notes the way they used to be able to? One possible approach would be to recognize the #hidden label, but I'm sure there are other way to implement as well.

Thanks for your help.

[eliandoran]

Archived notes allow you to hide the notes.

However — at one time there was a functional, though undocumented, hidden = true, key/value attribute that did hide notes. That internal flag no longer works in current builds.

On which version of Trilium?

[pyz0123-cpu]

Thanks again for your reply. A technical friend of mine says that the hidden = true key/value attribute worked in older Trilium builds, and that matches what I’ve read from the pre‑Archive / Hidden‑subtree era (around 2019–2020). It was never documented, but it did function at that time to hide notes from the tree. In current 0.101.x builds, that behavior no longer seems to work. And just to explain why this matters: I wanted to keep all the theming, admin, and configuration logic inside a dedicated Admin note. I don’t want to clutter that space with my actual content notes. The ability to hide notes would keep that separation clean. I was also hoping that hiding the note would still allow the theming to work — but through testing I’ve discovered that both archiving and hiding break the CSS theme logic. The CSS in those notes no longer gets applied. Finally, I tried placing the theming note into the Hidden subtree, and every time I restarted Trilium the note was deleted. I could undelete it from Recent Changes, but on each restart it disappeared again. It seems the note inherited an internal hidden/system flag that I couldn’t clear once it had been placed in that subtree. So the real question is this: why can’t we have a hidden note that still remains active, so theming can be applied without exposing that note to the rest of the content? A #hidden label could be one possible approach, but I’m sure there are other ways to implement this that would make it easier to keep theming/admin notes active while keeping them out of the main tree. If I am doing something wrong, please correct me. Thanks for your help and consideration.

…

On Mon, Feb 9, 2026 at 1:37 PM Elian Doran ***@***.***> wrote: Archived notes allow you to hide the notes. However — at one time there was a functional, though undocumented, hidden = true, key/value attribute that did hide notes. That internal flag no longer works in current builds. On which version of Trilium? — Reply to this email directly, view it on GitHub <#8605 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/B5IAVH2MYZJM2N5NLORP7RT4LD4Z3AVCNFSM6AAAAACT23KXQWVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTKNZUHA4DIMQ> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[hulmgulm]

I have an idea, why not have a root note with two sub notes: notes and admin. Put all the admin stuff in the admin note and your notes into the other note. Then you can hoist the notes note which will become your new root note and the admin stuff is then hidden.

[pyz0123-cpu]

Thanks for the reply, I appreciate it. Some questions: Is hoisting permanent or is it per-session? Will I have to hoist it every time I close Trilium and re-enter? Finally, after all this work and testing - I think the bottom line solution is to leave the ADMIN notes un-hidden so the CSS theming code works. Then I will just need to test the excludeFromExport=true attribute to see if that works. Thanks for the help and reply.