trilium_share_gruvbox/docs/switch-blog-theme.md

Switching the blog theme

The blog theme is not selected by a file name – it is controlled by the ~shareCss relation on the blog root note (Your Blog) inside Trilium. The relation points at a text/css note that holds the theme stylesheet. Everything below uses the notes of this repository's live blog; note IDs are given for reference.

Available themes

Theme	Repo file	Live note	Dark / light
Ash (active)	theme/blog_share_theme_ash.css	__THEME_ASH_ID__	panel/bone · ember+steel / paper+ink
Coffee (default)	theme/blog_share_theme_coffee.css	__THEME_COFFEE_ID__	espresso / latte-cream
Harbor	theme/blog_share_theme_harbor.css	__THEME_HARBOR_ID__	harbordark / paper
Gruvbox	theme/blog_share_theme_gruvbox.css	__THEME_GRUVBOX_ID__	gruvbox dark / light
Solarized	theme/blog_share_theme_solarized.css	__THEME_SOLARIZED_ID__	base03 / base3
Tokyo Night	theme/blog_share_theme_tokyonight.css	__THEME_TOKYONIGHT_ID__	storm / day

All six themes include a html.theme-light + html.theme-dark block, theme-aware 3D viewer overlays and Mermaid rendering. The 3D viewer reads the theme's CSS variables (--background-primary for the canvas, --background-active for the model material), so it adapts automatically to whichever theme is active – no script changes needed.

How the active theme is resolved

1. The blog root note (Your Blog, __BLOG_ROOT_ID__) carries ~shareCss → blog_share_theme_*.css.
2. The target note is a code note with mime text/css living under .blog (the share system note).
3. The public share renders the page and loads that note's CSS.

Switching themes

Pick the target note and re-point the relation. The theme note already exists in Trilium (see the table above), so only the relation needs to change.

Option A – via the Trilium UI

1. Find the target theme note under .blog (e.g. blog_share_theme_gruvbox.css).
2. Open Your Blog → Attributes → edit the ~shareCss relation to point at that note.
3. Hard-refresh the blog (Ctrl+F5). Done.

Option B – via ETAPI (scriptable)

TOKEN="your-etapi-token"
SERVER="https://YOUR-TRILIUM.example.com"

# 1. Delete the current shareCss relation on the blog root (__BLOG_ROOT_ID__)
curl -X DELETE "$SERVER/etapi/attributes/<attributeId>" -H "Authorization: $TOKEN"

# 2. Point shareCss at the desired theme note (example: Gruvbox __THEME_GRUVBOX_ID__)
curl -X POST "$SERVER/etapi/attributes" \
  -H "Authorization: $TOKEN" -H "Content-Type: application/json" \
  -d '{"noteId":"__BLOG_ROOT_ID__","type":"relation","name":"shareCss","value":"__THEME_GRUVBOX_ID__","isInheritable":true}'

The attribute ID of the old shareCss relation can be looked up via GET $SERVER/etapi/notes/__BLOG_ROOT_ID__/attributes (or the Trilium attribute list on the note).

Option C – create a fresh theme note from this repo

If you want to add or customise a theme on a new Trilium instance:

1. Create a code note with mime text/css under .blog, title e.g. blog_share_theme_coffee.css.
2. Copy the contents of the matching theme/blog_share_theme_*.css file into it.
3. Point ~shareCss on the blog root at the new note (Option A or B).

Tip: After a theme/content change the page may be cached – do a hard reload. If you run nginx proxy caching, also clear the cache (see AGENTS.md / the nginx guide).

Shared base stylesheet (since the theme refactor)

The palette-independent layout lives in blog_share_base.css (note under .blog, mime text/css). It is attached to the blog root with a second shareCss relation that is inherited (isInheritable), alongside the per-palette theme relation. When you switch the active palette you change ONLY the theme shareCss target; the base relation stays untouched.

Because the base is shared, add any new generic rule (focus ring, image caps, component layout) to blog_share_base.css instead of duplicating it across all six theme files. The themes now carry only the :root variables and the colour-specific components. For production you can serve the minified build via tools/minify_css.py.