imorland · Oct 28, 2026
diff --git a/docs/admin.md b/docs/admin.md
@@ -15,6 +15,25 @@ The Admin Dashboard has the following sections, being:
 
 Apart from the above-mentioned sections, the Admin Dashboard also allows you to manage your Extensions (including the flarum core extensions such as Tags) under the _Features_ section. Extensions which modify the forum theme, or allow you to use multiple languages are categorized under the _Themes_ and _Languages_ section respectively.
 
+## The Appearance page
+
+Besides the forum's colors and custom CSS, the Appearance page sets its logos and icons:
+
+- **Logo** and **Dark Mode Logo**, shown in the header.
+- **Email Logo**, shown at the top of emails. Without one, emails use a copy of the logo.
+- **Favicon**, shown in browser tabs and bookmarks. A square image at least 48 pixels across stays sharp, and an `.ico` file works too. Flarum also stores it as an `.ico` for older browsers and other software.
+- **App Icon**, which phones show when someone adds the forum to their home screen. Upload a square image at least 512 pixels across. The page previews it as iPhones and Android show it, and **App Icon Background** fills its transparent parts on iPhones and iPads, and the space around it on Android. Without a favicon, the app icon is used as the favicon too.
+
+If a theme sets one of these images, the page shows it, marked as set by that theme, but it can't be changed there.
+
+Flarum answers requests for `/favicon.ico` itself. On nginx, Flarum's suggested configuration serves `.ico` files straight from the disk, so to have Flarum answer that request too, add this before its other `location` blocks:
+
+```nginx
+location = /favicon.ico {
+  try_files $uri /index.php?$query_string;
+}
+```
+
 ## The Advanced page
 
 The Advanced page holds settings that most forums never need to change, so it is hidden from the admin menu until you turn it on.

diff --git a/docs/extend/theme.md b/docs/extend/theme.md
@@ -57,6 +57,48 @@ Independently of the container, the discussion post stream is capped on wide scr
 }
 ```
 
+## Logos and Icons
+
+From Flarum 2.1, a theme can set the forum's logos and icons with the `Theme` extender:
+
+```php
+use Flarum\Extend;
+
+return [
+    (new Extend\Theme())
+        ->logo(__DIR__.'/resources/logo.svg')
+        ->logoDarkMode(__DIR__.'/resources/logo-dark.svg')
+        ->emailLogo(__DIR__.'/resources/logo-email.png')
+        ->favicon(__DIR__.'/resources/favicon.png', svg: __DIR__.'/resources/favicon.svg')
+        ->appIcon(__DIR__.'/resources/app-icon.png', background: '#0f172a'),
+];
+```
+
+| Method | Sets |
+|---|---|
+| `logo(string $file)` | The forum logo. A PNG, JPEG, WebP, GIF or SVG file. |
+| `logoDarkMode(string $file)` | The logo shown in dark mode. The same formats as `logo()`. |
+| `emailLogo(string $file)` | The logo at the top of emails. Not an SVG, which mail clients can't be relied on to show. |
+| `favicon(string $file, ?string $svg = null)` | The favicon, from a PNG, JPEG, WebP or GIF, ideally at least 48px square, and optionally an SVG version for browsers that support SVG favicons. |
+| `appIcon(string $file, ?string $background = null)` | The icon phones show when the forum is added to a home screen, from a square PNG, JPEG, WebP or GIF at least 512px. The background colour fills its transparent parts on iPhones and iPads and the space around it on Android, and defaults to the one set on the Appearance page. |
+
+Each image goes through the same steps as an uploaded one. A raster logo is stored at the [logo size and quality](#logo-size-and-quality), and an SVG logo is used as it is. The favicon becomes a `.ico` and a PNG, and the app icon becomes Apple's touch icon, the web app manifest's icons and a maskable icon. Without `emailLogo()`, emails use a copy of the logo, unless it is an SVG.
+
+The images are drawn into the forum's assets once, and again only when a file or one of its options changes. An image that can't be read is logged and left out. On the Appearance page, admins see the images the theme sets, marked as set by your extension, but can't change them.
+
+A path that doesn't exist, or an SVG where one isn't allowed, throws an `InvalidArgumentException` when you call the method.
+
+### Web App Manifest
+
+Flarum serves a web app manifest at `/manifest`, which phones read for the name and icons of a home screen shortcut. It opens the forum in the browser. An extension can change it with `manifest()`, for example to open the forum as an installed app:
+
+```php
+(new Extend\Theme())
+    ->manifest(fn (array $manifest) => ['display' => 'standalone'] + $manifest),
+```
+
+Pages link the manifest once there is an app icon, or an extension has changed it.
+
 ## Logo Size and Quality
 
 From Flarum 2.1, an uploaded logo, and the dark mode logo, are stored 90px tall as WebP at quality 90. The header shows the logo at most 30px tall, so it stays sharp on screens with up to three times the pixel density. A theme that shows the logo larger can store it taller, or at another quality, with the `Theme` extender:
@@ -66,13 +108,13 @@ use Flarum\Extend;
 
 return [
     (new Extend\Theme())
-        ->logo(height: 126, quality: 95),
+        ->logoSize(height: 126, quality: 95),
 ];
 ```
 
 Store the logo at its displayed height times the pixel density it should stay sharp at: a logo shown 42px tall needs 126px for 3x screens. Both arguments are optional, and the one you leave out keeps its default. The quality runs from 1 to 100. An animated logo is stored as GIF, which has no quality setting.
 
-The values apply when a logo is uploaded. A logo that is already stored keeps its size and quality until an admin uploads it again.
+The values apply when a logo is uploaded, or set with `logo()`. A logo that is already stored keeps its size and quality until an admin uploads it again.
 
 ## Switching Between Themes
 

diff --git a/docs/extend/update-2_x.md b/docs/extend/update-2_x.md
@@ -8,7 +8,13 @@ If you need help applying these changes or using new features, please start a di
 
 ## 2.1 Changes
 
+### Logos and Icons
+
+Forums can now set an app icon, which Flarum turns into Apple's touch icon and the icons of a new web app manifest at `/manifest`, and the favicon is also stored as a `.ico`. The `Theme` extender can set every logo and icon with `logo()`, `logoDarkMode()`, `emailLogo()`, `favicon()` and `appIcon()`, and change the manifest with `manifest()`. See [Logos and Icons](theme.md#logos-and-icons).
+
+`UploadImageController::makeImage()` may now also return the image as a string. An extension that serves its own web app manifest, such as a progressive web app, should change Flarum's with `manifest()` instead, as browsers use the first manifest a page links.
+
 ### Logos
 
-Uploaded logos are now stored 90px tall at WebP quality 90, rather than 60px tall at quality 75. A theme that shows the logo larger can choose the stored height and quality with `(new Extend\Theme())->logo()`. See [Logo Size and Quality](theme.md#logo-size-and-quality).
+Uploaded logos are now stored 90px tall at WebP quality 90, rather than 60px tall at quality 75. A theme that shows the logo larger can choose the stored height and quality with `(new Extend\Theme())->logoSize()`. See [Logo Size and Quality](theme.md#logo-size-and-quality).