Ship all three blog themes (Coffee/Harbor/Gruvbox) with palette images, theme-switch guide; make 3D viewer read theme CSS variables

2026-09-07 19:43:51 +02:00
parent b7a59be0d7
commit 9806483add
11 changed files with 3877 additions and 14 deletions
@@ -0,0 +1,65 @@
+# 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 (`Richard's 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 |
+|---|---|---|---|
+| Coffee (default) | `theme/blog_share_theme_coffee.css` | `NqZXcFRGi3II` | espresso / latte-cream |
+| Harbor | `theme/blog_share_theme_harbor.css` | `Ep54EDTwKxup` | harbordark / paper |
+| Gruvbox | `theme/blog_share_theme_gruvbox.css` | `edhL5cByGwqA` | gruvbox dark / light |
+
+All three 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 (`Richard's Blog`, `OKjkpgmXZY1L`) 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 `Richard's Blog` → Attributes → edit the `~shareCss` relation to point at that note.
+3. Hard-refresh the blog (Ctrl+F5). Done.
+
+### Option B – via ETAPI (scriptable)
+
+```bash
+TOKEN="your-etapi-token"
+SERVER="https://notes.familie-zink.org"
+
+# 1. Delete the current shareCss relation on the blog root (OKjkpgmXZY1L)
+curl -X DELETE "$SERVER/etapi/attributes/<attributeId>" -H "Authorization: $TOKEN"
+
+# 2. Point shareCss at the desired theme note (example: Gruvbox edhL5cByGwqA)
+curl -X POST "$SERVER/etapi/attributes" \
+  -H "Authorization: $TOKEN" -H "Content-Type: application/json" \
+  -d '{"noteId":"OKjkpgmXZY1L","type":"relation","name":"shareCss","value":"edhL5cByGwqA","isInheritable":true}'
+```
+
+The attribute ID of the old `shareCss` relation can be looked up via
+`GET $SERVER/etapi/notes/OKjkpgmXZY1L/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).