searxng-kanagawa

A Kanagawa color theme for SearXNG, plus an optional custom logo.

Two variants are included in a single CSS file:

Variant	Style	Based on
Wave	Dark	sumiInk backgrounds, fujiWhite text, crystalBlue links
Lotus	Light	lotusWhite backgrounds, lotusInk text, lotusBlue links

The active variant follows SearXNG's normal Theme style preference (Auto / Light / Dark / Black). With Auto, it switches on your system's prefers-color-scheme.

---

How it works

SearXNG has no plugin system for themes, but the simple theme defines all of its colors as CSS custom properties (variables). kanagawa.css simply overrides those variables, so no fork or rebuild is required — it loads after the compiled theme CSS and recolors everything.

Important — selector specificity. SearXNG defines its variables on :root.theme-dark, :root.theme-auto, etc. (see definitions.less). :root.theme-* has specificity (0,2,0). Overrides therefore must use the same :root.theme-* selectors — html.theme-* (0,1,1) is lower specificity and silently loses the cascade no matter the load order. This is why kanagawa.css targets :root.theme-*.

---

Installation

Files involved (the logo/favicon images are optional):

File	Mount target	Purpose
kanagawa.css	…/searx/static/kanagawa.css	Theme color variables + logo CSS
quinsearch-logo.png	…/searx/static/quinsearch-logo.png	Full lockup (shield + wordmark), shown on the start page
quinsearch-shield.png	…/searx/static/quinsearch-shield.png	Shield only, shown in the results header
quinsearch-favicon.png	…/searx/static/quinsearch-favicon.png	Square shield used as the favicon
base.html	…/searx/templates/simple/base.html	Patched template (loads kanagawa.css, sets favicon)

base.html is a verbatim copy of the upstream template with a single <link> added:

<link rel="stylesheet" href="{{ url_for('static', filename='kanagawa.css') }}?v=2" type="text/css" media="screen">

Docker (volume mounts)

Place the files next to your docker-compose.yml, then add the volume entries to the core service:

services:
  core:
    # ... your existing config ...
    volumes:
      - ./config/:/etc/searxng/:Z
      - ./data:/var/cache/searxng/
      - ./kanagawa.css:/usr/local/searxng/searx/static/kanagawa.css:ro
      - ./quinsearch-logo.png:/usr/local/searxng/searx/static/quinsearch-logo.png:ro
      - ./quinsearch-shield.png:/usr/local/searxng/searx/static/quinsearch-shield.png:ro
      - ./quinsearch-favicon.png:/usr/local/searxng/searx/static/quinsearch-favicon.png:ro
      - ./base.html:/usr/local/searxng/searx/templates/simple/base.html:ro

Because Jinja caches compiled templates in memory, a change to base.html needs a full recreate, not just a restart:

docker compose up -d --force-recreate core

Editing only kanagawa.css or the logo afterwards does not need a recreate — the files are bind-mounted and served live (but see Caching below).

Without Docker (bare-metal / venv)

# the directory containing the searx/ package, e.g. /usr/local/searxng
SEARXNG_ROOT=/usr/local/searxng

cp kanagawa.css           "$SEARXNG_ROOT/searx/static/kanagawa.css"
cp quinsearch-logo.png    "$SEARXNG_ROOT/searx/static/quinsearch-logo.png"
cp quinsearch-shield.png  "$SEARXNG_ROOT/searx/static/quinsearch-shield.png"
cp quinsearch-favicon.png "$SEARXNG_ROOT/searx/static/quinsearch-favicon.png"
cp base.html              "$SEARXNG_ROOT/searx/templates/simple/base.html"

Restart your SearXNG process (systemd, supervisor, etc.).

Browser extension (Stylus — client-side only, no server access)

1. Install the Stylus extension.
2. Manage → Write new style, paste the contents of kanagawa.css.
3. Set it to apply on your SearXNG domain, e.g. search.example.com. Save.

Stylus does not use base.html, and the logo rule expects the image at /static/quinsearch-logo.png — either upload that file or delete the logo block from the pasted CSS.

---

Caching

If you have a reverse proxy / CDN in front of SearXNG (nginx, openresty, Caddy, Cloudflare, …), it will likely cache /static/* for a long time. After changing kanagawa.css or the logo you may keep seeing the old version even in an incognito window, because that bypasses only the browser cache, not the proxy/edge cache.

To confirm whether the proxy is serving a stale copy:

# what the container actually has on disk:
docker exec searxng-core grep -c theme-dark /usr/local/searxng/searx/static/kanagawa.css

# what the proxy serves on the normal URL:
curl -s https://YOUR_DOMAIN/static/kanagawa.css | grep -c theme-dark

# same file, cache-busted:
curl -s "https://YOUR_DOMAIN/static/kanagawa.css?v=$(date +%s)" | grep -c theme-dark

If the disk and cache-busted counts match but the plain URL differs, the proxy cache is stale. Two ways to deal with it:

1. Version bump (already wired in). The <link> in base.html and the logo URL in kanagawa.css carry a ?v=N query string. Increment N whenever you change the files — the new URL is a fresh cache key, so the proxy fetches the updated file. (After bumping the version in base.html, recreate the container so Jinja reloads it.)
2. Purge the asset from your proxy/CDN cache, or exclude /static/kanagawa.css and /static/quinsearch-logo.png from caching while you iterate.

---

Customizing the logo & favicon

The logo is swapped purely in CSS (kanagawa.css): the inline SearXNG <svg> inside #search_logo is hidden and the link gets a PNG as a background image. Two images are used so the start page and the results header can differ:

Where	Selector	Image
Results header	#search_logo	quinsearch-shield.png (shield only)
Start page	.index_endpoint #search_logo	quinsearch-logo.png (full lockup)

• Replace the PNGs with your own (transparent background recommended).
• If an image has a different aspect ratio, adjust the matching width/height in kanagawa.css (the shield is ~0.80:1, the full lockup ~2.30:1).
• The favicon is set in base.html and points at quinsearch-favicon.png (a 256×256 square shield).
• To keep the stock SearXNG logo, delete the QuinSearch logo block from kanagawa.css; to keep the stock favicon, restore the original <link rel="icon"> lines in base.html.

---

Color palette reference

Name	Hex	Role
sumiInk0	#16161D	Darkest background (header/footer)
sumiInk1	#1F1F28	Default background
sumiInk2	#2A2A37	Raised surfaces (search bar, answer box)
sumiInk3	#363646	Borders, selected result
sumiInk4	#54546D	Muted borders, line numbers
fujiWhite	#DCD7BA	Default foreground
fujiGray	#727169	Dimmed text (dates, engines)
crystalBlue	#7E9CD8	Links, buttons, accent
springBlue	#7FB4CA	Highlighted links
oniViolet	#957FB8	Visited links
springGreen	#98BB6C	Result URLs
carpYellow	#E6C384	Description highlights
waveBlue1	#223249	Autocomplete hover
waveBlue2	#2D4F67	Search bar hover
autumnRed	#C34043	Crest lions / hand
boatYellow2	#C0A36E	Crest ochre half
samuraiRed	#E82424	Errors
roninYellow	#FF9E3B	Warnings
autumnGreen	#76946A	Success