75 lines
4.1 KiB
Markdown
75 lines
4.1 KiB
Markdown
# 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 |
|
||
|---|---|---|---|
|
||
| **Ash (active)** | `theme/blog_share_theme_ash.css` | `OCbcTyzbQJA2` | panel/bone · ember+steel / paper+ink |
|
||
| 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 |
|
||
| Solarized | `theme/blog_share_theme_solarized.css` | `UFxPR5IpTyfj` | base03 / base3 |
|
||
| Tokyo Night | `theme/blog_share_theme_tokyonight.css` | `bf1OKYo3msZm` | 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 (`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).
|
||
|
||
## 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`.
|