README links to the documentation website, social preview image

README.md

@@ -18,14 +18,14 @@ No app store, no account, no server: open the page, connect, done.
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
 [![Vite](https://img.shields.io/badge/Vite-8-646cff?logo=vite&logoColor=white)](https://vite.dev/)
 [![Tailwind CSS](https://img.shields.io/badge/Tailwind-4-06b6d4?logo=tailwindcss&logoColor=white)](https://tailwindcss.com/)
-[![PWA](https://img.shields.io/badge/PWA-installable-5a0fc8?logo=pwa&logoColor=white)](docs/getting-started.md#install-as-an-app)
+[![PWA](https://img.shields.io/badge/PWA-installable-5a0fc8?logo=pwa&logoColor=white)](https://firsttris.github.io/reactive-volcano-app/docs/getting-started.html#install-as-an-app)
 
 [**▶ Open the app**](https://firsttris.github.io/reactive-volcano-app/) •
 [Why?](#-why) •
 [Features](#-features) •
 [Get started](#-get-started) •
 [Self-hosting](#-self-hosting) •
-[Documentation](docs/README.md) •
+[Documentation](https://firsttris.github.io/reactive-volcano-app/docs/) •
 [Development](#️-development)
 
 <img src="docs/hero.png" alt="The control screens for a desktop vaporizer, a portable with boost modes and a portable with battery display" width="900">
@@ -38,7 +38,7 @@ No app store, no account, no server: open the page, connect, done.
 > **Unofficial, independent project.** Not affiliated with, endorsed, sponsored or authorized by
 > Storz & Bickel GmbH. *VOLCANO*, *VENTY*, *VEAZY*, *CRAFTY* and *STORZ & BICKEL* are trademarks of
 > their respective owner and are used here only to name the devices this app is compatible with.
-> For the official app, firmware and support, go to the manufacturer. See [Legal notice](docs/legal.md).
+> For the official app, firmware and support, go to the manufacturer. See [Legal notice](https://firsttris.github.io/reactive-volcano-app/docs/legal.html).
 
 ## 💡 Why?
 
@@ -83,7 +83,7 @@ brightness and battery work, the rest is hidden.
 
 **Across the app**: light and dark mode (follows the system), English and German (follows the
 browser), installable PWA with offline start, the screen stays on while heating or running a workflow,
-clear error messages when the connection drops. Every screen is described in [Usage](docs/usage.md).
+clear error messages when the connection drops. Every screen is described in [Usage](https://firsttris.github.io/reactive-volcano-app/docs/usage.html).
 
 ## 📸 Screenshots
 
@@ -112,11 +112,11 @@ clear error messages when the connection drops. Every screen is described in [Us
 | Platform | Works with | Notes |
 |---|---|---|
 | Android, Windows, macOS, ChromeOS | Chrome, Edge, Opera | Web Bluetooth is on by default |
-| Linux | Chrome, Chromium | enable `chrome://flags/#enable-web-bluetooth` once, see [Getting started](docs/getting-started.md#linux) |
+| Linux | Chrome, Chromium | enable `chrome://flags/#enable-web-bluetooth` once, see [Getting started](https://firsttris.github.io/reactive-volcano-app/docs/getting-started.html#linux) |
 | iOS, iPadOS | [Bluefy](https://apps.apple.com/app/bluefy-web-ble-browser/id1492822055) | Safari has no Web Bluetooth |
 | Firefox, Safari | ❌ | no Web Bluetooth support |
 
-Device not found? Work through [Troubleshooting](docs/troubleshooting.md): it starts with Chrome's
+Device not found? Work through [Troubleshooting](https://firsttris.github.io/reactive-volcano-app/docs/troubleshooting.html): it starts with Chrome's
 built-in `chrome://bluetooth-internals` page and tells you in three steps whether the adapter, the
 browser or the device is the problem.
 
@@ -130,7 +130,7 @@ docker run -d --name vaporizer-app -p 8080:8080 --restart unless-stopped tristan
 ```
 
 The container runs nginx without root and listens on port **8080** (older images: 80, see
-[upgrading](docs/self-hosting.md#updates)).
+[upgrading](https://firsttris.github.io/reactive-volcano-app/docs/self-hosting.html#updates)).
 
 <details>
 <summary><b>Docker Compose</b></summary>
@@ -160,26 +160,26 @@ systemctl --user daemon-reload && systemctl --user start volcano-app
 > [!NOTE]
 > Browsers only allow Bluetooth on **secure origins**: `https://…` or `http://localhost`. To use your
 > instance from another device, put it behind a reverse proxy with HTTPS. Examples for Caddy, nginx and
-> Traefik, and how to serve the app under a sub-path, are in [Self-hosting](docs/self-hosting.md).
+> Traefik, and how to serve the app under a sub-path, are in [Self-hosting](https://firsttris.github.io/reactive-volcano-app/docs/self-hosting.html).
 
 ## 📚 Documentation
 
 Also as a website with search: **https://firsttris.github.io/reactive-volcano-app/docs/**
 
 | | |
 |---|---|
-| [Getting started](docs/getting-started.md) | browsers, Linux flag, iOS, connecting, installing as an app, updates |
-| [Usage](docs/usage.md) | every screen for each device: control, boost, settings, diagnosis, find my device |
-| [Workflows](docs/workflows.md) | how a workflow runs, editing, the JSON format for import and export |
-| [Self-hosting](docs/self-hosting.md) | Docker, Compose, Podman, HTTPS with Caddy / nginx / Traefik, sub-paths, static hosting |
-| [Troubleshooting & FAQ](docs/troubleshooting.md) | device not found, connection drops, Linux, iOS, common questions |
-| [Privacy & security](docs/privacy-security.md) | what the app stores, what it sends (nothing), permissions, secure context |
-| [Architecture](docs/architecture.md) | layers, data flow, Bluetooth queue, stores, routing, PWA, design decisions |
-| [Bluetooth protocol](docs/protocol.md) | services, characteristics and encodings for each device family |
-| [Development](docs/development.md) | setup, scripts, project structure, conventions, translations, adding a device, debugging on Android |
-| [Testing](docs/testing.md) | unit tests, the Bluetooth mock, end-to-end tests, screenshots, CI |
-| [Releases & deployment](docs/releases.md) | GitHub Pages, versioning, Docker images, the release workflow |
-| [Legal notice](docs/legal.md) | trademarks, no affiliation, no warranty, safety, license |
+| [Getting started](https://firsttris.github.io/reactive-volcano-app/docs/getting-started.html) | browsers, Linux flag, iOS, connecting, installing as an app, updates |
+| [Usage](https://firsttris.github.io/reactive-volcano-app/docs/usage.html) | every screen for each device: control, boost, settings, diagnosis, find my device |
+| [Workflows](https://firsttris.github.io/reactive-volcano-app/docs/workflows.html) | how a workflow runs, editing, the JSON format for import and export |
+| [Self-hosting](https://firsttris.github.io/reactive-volcano-app/docs/self-hosting.html) | Docker, Compose, Podman, HTTPS with Caddy / nginx / Traefik, sub-paths, static hosting |
+| [Troubleshooting & FAQ](https://firsttris.github.io/reactive-volcano-app/docs/troubleshooting.html) | device not found, connection drops, Linux, iOS, common questions |
+| [Privacy & security](https://firsttris.github.io/reactive-volcano-app/docs/privacy-security.html) | what the app stores, what it sends (nothing), permissions, secure context |
+| [Architecture](https://firsttris.github.io/reactive-volcano-app/docs/architecture.html) | layers, data flow, Bluetooth queue, stores, routing, PWA, design decisions |
+| [Bluetooth protocol](https://firsttris.github.io/reactive-volcano-app/docs/protocol.html) | services, characteristics and encodings for each device family |
+| [Development](https://firsttris.github.io/reactive-volcano-app/docs/development.html) | setup, scripts, project structure, conventions, translations, adding a device, debugging on Android |
+| [Testing](https://firsttris.github.io/reactive-volcano-app/docs/testing.html) | unit tests, the Bluetooth mock, end-to-end tests, screenshots, CI |
+| [Releases & deployment](https://firsttris.github.io/reactive-volcano-app/docs/releases.html) | GitHub Pages, versioning, Docker images, the release workflow |
+| [Legal notice](https://firsttris.github.io/reactive-volcano-app/docs/legal.html) | trademarks, no affiliation, no warranty, safety, license |
 
 ## 🛠️ Development
 
@@ -196,8 +196,8 @@ No device at hand? The end-to-end tests run the whole app against a simulated We
 
 **Stack**: SolidJS with `@solidjs/router` · Tailwind CSS 4 and [solid-ui](https://www.solid-ui.com)
 (Kobalte) · Paraglide JS for English and German · `p-queue` to serialize every GATT operation ·
-`vite-plugin-pwa` · Vitest, Playwright and Biome. Details in [Development](docs/development.md) and
-[Architecture](docs/architecture.md).
+`vite-plugin-pwa` · Vitest, Playwright and Biome. Details in [Development](https://firsttris.github.io/reactive-volcano-app/docs/development.html) and
+[Architecture](https://firsttris.github.io/reactive-volcano-app/docs/architecture.html).
 
 ```bash
 npm run typecheck && npm run lint && npm test && npm run test:e2e

README_de.md

@@ -18,14 +18,14 @@ Kein App-Store, kein Konto, kein Server: Seite öffnen, verbinden, fertig.
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
 [![Vite](https://img.shields.io/badge/Vite-8-646cff?logo=vite&logoColor=white)](https://vite.dev/)
 [![Tailwind CSS](https://img.shields.io/badge/Tailwind-4-06b6d4?logo=tailwindcss&logoColor=white)](https://tailwindcss.com/)
-[![PWA](https://img.shields.io/badge/PWA-installierbar-5a0fc8?logo=pwa&logoColor=white)](docs/getting-started.md#install-as-an-app)
+[![PWA](https://img.shields.io/badge/PWA-installierbar-5a0fc8?logo=pwa&logoColor=white)](https://firsttris.github.io/reactive-volcano-app/docs/getting-started.html#install-as-an-app)
 
 [**▶ App öffnen**](https://firsttris.github.io/reactive-volcano-app/) •
 [Warum?](#-warum) •
 [Funktionen](#-funktionen) •
 [Loslegen](#-loslegen) •
 [Selbst hosten](#-selbst-hosten) •
-[Dokumentation](docs/README.md) •
+[Dokumentation](https://firsttris.github.io/reactive-volcano-app/docs/) •
 [Entwicklung](#️-entwicklung)
 
 <img src="docs/hero.png" alt="Die Steuerung für einen Tisch-Vaporizer, ein Handgerät mit Boost-Modi und ein Handgerät mit Akkuanzeige" width="900">
@@ -39,7 +39,7 @@ Kein App-Store, kein Konto, kein Server: Seite öffnen, verbinden, fertig.
 > wird von ihr weder unterstützt noch autorisiert. *VOLCANO*, *VENTY*, *VEAZY*, *CRAFTY* und
 > *STORZ & BICKEL* sind Marken ihres jeweiligen Inhabers und werden hier nur genannt, um zu beschreiben,
 > mit welchen Geräten die App kompatibel ist. Offizielle App, Firmware und Support gibt es beim
-> Hersteller. Siehe [Rechtliche Hinweise](docs/legal.md).
+> Hersteller. Siehe [Rechtliche Hinweise](https://firsttris.github.io/reactive-volcano-app/docs/legal.html).
 
 ## 💡 Warum?
 
@@ -86,7 +86,7 @@ Boost, Helligkeit und Akku funktionieren, der Rest wird ausgeblendet.
 **In der ganzen App**: hell und dunkel (folgt dem System), Deutsch und Englisch (folgt dem Browser),
 installierbare PWA mit Offline-Start, der Bildschirm bleibt an, solange geheizt wird oder ein Workflow
 läuft, klare Meldungen, wenn die Verbindung abreißt. Jede Seite ist in der
-[Bedienung](docs/usage.md) beschrieben (englisch).
+[Bedienung](https://firsttris.github.io/reactive-volcano-app/docs/usage.html) beschrieben (englisch).
 
 ## 📸 Screenshots
 
@@ -116,11 +116,11 @@ läuft, klare Meldungen, wenn die Verbindung abreißt. Jede Seite ist in der
 | Plattform | Funktioniert mit | Hinweis |
 |---|---|---|
 | Android, Windows, macOS, ChromeOS | Chrome, Edge, Opera | Web Bluetooth ist standardmäßig an |
-| Linux | Chrome, Chromium | einmal `chrome://flags/#enable-web-bluetooth` aktivieren, siehe [Getting started](docs/getting-started.md#linux) |
+| Linux | Chrome, Chromium | einmal `chrome://flags/#enable-web-bluetooth` aktivieren, siehe [Getting started](https://firsttris.github.io/reactive-volcano-app/docs/getting-started.html#linux) |
 | iOS, iPadOS | [Bluefy](https://apps.apple.com/app/bluefy-web-ble-browser/id1492822055) | Safari kann kein Web Bluetooth |
 | Firefox, Safari | ❌ | kein Web Bluetooth |
 
-Gerät wird nicht gefunden? Die [Fehlersuche](docs/troubleshooting.md) beginnt mit Chromes eingebauter
+Gerät wird nicht gefunden? Die [Fehlersuche](https://firsttris.github.io/reactive-volcano-app/docs/troubleshooting.html) beginnt mit Chromes eingebauter
 Seite `chrome://bluetooth-internals` und zeigt in drei Schritten, ob Adapter, Browser oder Gerät das
 Problem ist.
 
@@ -134,7 +134,7 @@ docker run -d --name vaporizer-app -p 8080:8080 --restart unless-stopped tristan
 ```
 
 Der Container betreibt nginx ohne Root-Rechte und lauscht auf Port **8080** (ältere Images: 80, siehe
-[Aktualisieren](docs/self-hosting.md#updates)).
+[Aktualisieren](https://firsttris.github.io/reactive-volcano-app/docs/self-hosting.html#updates)).
 
 <details>
 <summary><b>Docker Compose</b></summary>
@@ -165,27 +165,27 @@ systemctl --user daemon-reload && systemctl --user start volcano-app
 > Browser erlauben Bluetooth nur in einem **sicheren Kontext**: `https://…` oder `http://localhost`.
 > Wer seine Instanz von einem anderen Gerät aus nutzen will, braucht einen Reverse Proxy mit HTTPS.
 > Beispiele für Caddy, nginx und Traefik und den Betrieb unter einem Unterpfad stehen in
-> [Self-hosting](docs/self-hosting.md).
+> [Self-hosting](https://firsttris.github.io/reactive-volcano-app/docs/self-hosting.html).
 
 ## 📚 Dokumentation
 
-Die ausführliche Dokumentation ist auf Englisch: [docs/README.md](docs/README.md), auch als Website
+Die ausführliche Dokumentation ist auf Englisch: [docs/README.md](https://firsttris.github.io/reactive-volcano-app/docs/), auch als Website
 mit Suche: **https://firsttris.github.io/reactive-volcano-app/docs/**
 
 | | |
 |---|---|
-| [Getting started](docs/getting-started.md) | Browser, Linux-Flag, iOS, Verbinden, als App installieren, Updates |
-| [Usage](docs/usage.md) | jede Seite je Gerät: Steuerung, Boost, Einstellungen, Diagnose, Gerät finden |
-| [Workflows](docs/workflows.md) | Ablauf eines Workflows, Bearbeiten, JSON-Format für Import und Export |
-| [Self-hosting](docs/self-hosting.md) | Docker, Compose, Podman, HTTPS mit Caddy / nginx / Traefik, Unterpfade |
-| [Troubleshooting & FAQ](docs/troubleshooting.md) | Gerät nicht gefunden, Verbindungsabbrüche, Linux, iOS, häufige Fragen |
-| [Privacy & security](docs/privacy-security.md) | was die App speichert, was sie sendet (nichts), Berechtigungen |
-| [Architecture](docs/architecture.md) | Schichten, Datenfluss, Bluetooth-Queue, Stores, Routing, PWA, Entscheidungen |
-| [Bluetooth protocol](docs/protocol.md) | Services, Characteristics und Kodierung je Gerätefamilie |
-| [Development](docs/development.md) | Einrichtung, Skripte, Projektstruktur, Konventionen, Übersetzungen, neues Gerät |
-| [Testing](docs/testing.md) | Unit-Tests, Bluetooth-Mock, End-to-End-Tests, Screenshots, CI |
-| [Releases & deployment](docs/releases.md) | GitHub Pages, Versionen, Docker-Images, Release-Workflow |
-| [Legal notice](docs/legal.md) | Marken, keine Verbindung zum Hersteller, keine Gewährleistung, Sicherheit, Lizenz |
+| [Getting started](https://firsttris.github.io/reactive-volcano-app/docs/getting-started.html) | Browser, Linux-Flag, iOS, Verbinden, als App installieren, Updates |
+| [Usage](https://firsttris.github.io/reactive-volcano-app/docs/usage.html) | jede Seite je Gerät: Steuerung, Boost, Einstellungen, Diagnose, Gerät finden |
+| [Workflows](https://firsttris.github.io/reactive-volcano-app/docs/workflows.html) | Ablauf eines Workflows, Bearbeiten, JSON-Format für Import und Export |
+| [Self-hosting](https://firsttris.github.io/reactive-volcano-app/docs/self-hosting.html) | Docker, Compose, Podman, HTTPS mit Caddy / nginx / Traefik, Unterpfade |
+| [Troubleshooting & FAQ](https://firsttris.github.io/reactive-volcano-app/docs/troubleshooting.html) | Gerät nicht gefunden, Verbindungsabbrüche, Linux, iOS, häufige Fragen |
+| [Privacy & security](https://firsttris.github.io/reactive-volcano-app/docs/privacy-security.html) | was die App speichert, was sie sendet (nichts), Berechtigungen |
+| [Architecture](https://firsttris.github.io/reactive-volcano-app/docs/architecture.html) | Schichten, Datenfluss, Bluetooth-Queue, Stores, Routing, PWA, Entscheidungen |
+| [Bluetooth protocol](https://firsttris.github.io/reactive-volcano-app/docs/protocol.html) | Services, Characteristics und Kodierung je Gerätefamilie |
+| [Development](https://firsttris.github.io/reactive-volcano-app/docs/development.html) | Einrichtung, Skripte, Projektstruktur, Konventionen, Übersetzungen, neues Gerät |
+| [Testing](https://firsttris.github.io/reactive-volcano-app/docs/testing.html) | Unit-Tests, Bluetooth-Mock, End-to-End-Tests, Screenshots, CI |
+| [Releases & deployment](https://firsttris.github.io/reactive-volcano-app/docs/releases.html) | GitHub Pages, Versionen, Docker-Images, Release-Workflow |
+| [Legal notice](https://firsttris.github.io/reactive-volcano-app/docs/legal.html) | Marken, keine Verbindung zum Hersteller, keine Gewährleistung, Sicherheit, Lizenz |
 
 ## 🛠️ Entwicklung
 
@@ -202,8 +202,8 @@ Web-Bluetooth-Stack laufen; mit `npm run test:e2e:ui` kann man sich durchklicken
 
 **Stack**: SolidJS mit `@solidjs/router` · Tailwind CSS 4 und [solid-ui](https://www.solid-ui.com)
 (Kobalte) · Paraglide JS für Deutsch und Englisch · `p-queue`, das jeden GATT-Zugriff serialisiert ·
-`vite-plugin-pwa` · Vitest, Playwright und Biome. Mehr in [Development](docs/development.md) und
-[Architecture](docs/architecture.md).
+`vite-plugin-pwa` · Vitest, Playwright und Biome. Mehr in [Development](https://firsttris.github.io/reactive-volcano-app/docs/development.html) und
+[Architecture](https://firsttris.github.io/reactive-volcano-app/docs/architecture.html).
 
 ```bash
 npm run typecheck && npm run lint && npm test && npm run test:e2e

docs/development.md

@@ -17,6 +17,8 @@ adding a device and debugging on a phone.
 - [Working without a device](#working-without-a-device)
 - [Debugging on Android](#debugging-on-android)
 - [Updating screenshots](#updating-screenshots)
+- [App icons](#app-icons)
+- [Social preview](#social-preview)
 
 ## Requirements
 
@@ -55,6 +57,7 @@ secure context, so Web Bluetooth works there. For another device on your network
 | `npm run test:e2e:ui` / `test:e2e:debug` / `test:e2e:report` | Playwright UI mode, debugger, last report |
 | `npm run screenshots` | renders the images in `docs/` ([below](#updating-screenshots)) |
 | `npm run icons` | renders the app icons in `public/` from `scripts/icons/icon.svg` ([below](#app-icons)) |
+| `npm run social-preview` | renders `docs/social-preview.png` ([below](#social-preview)) |
 | `npm run i18n` | compiles `messages/*.json` into `src/paraglide` |
 | `npm run release:patch` / `minor` / `major` | bumps the version, tags and pushes ([Releases](releases.md)) |
 
@@ -242,6 +245,19 @@ Keep the artwork inside the central circle (80 % of the width): Android crops ma
 circle or squircle. `npm run screenshots` also refreshes `public/screenshots/`, which Android shows in
 the install dialog. Use `CHROMIUM_PATH` here as well if the bundled browser is missing.
 
+## Social preview
+
+The image GitHub shows when the repository is shared (1280 × 640) is rendered from
+`scripts/social-preview/social-preview.html`, with the icon and the screenshots from `docs/`:
+
+```bash
+npm run social-preview
+```
+
+It writes `docs/social-preview.png`. Upload it under *Settings → General → Social preview*; GitHub does
+not read it from the repository. Render it again after `npm run screenshots` or a change to the icon.
+`CHROMIUM_PATH` works here too.
+
 ---
 
 Next: [Testing](testing.md) · [Architecture](architecture.md) · [Documentation index](README.md)

package.json

@@ -13,6 +13,7 @@
     "build:root": "npm run typecheck && vite build",
     "preview": "vite preview",
     "icons": "node scripts/icons/generate.mjs",
+    "social-preview": "node scripts/social-preview/render.mjs",
     "test": "npm run i18n && vitest run",
     "test:watch": "vitest",
     "test:ui": "vitest --ui",