From 97fb7f023579839079a04154b9cb00603aad1d98 Mon Sep 17 00:00:00 2001
From: Johannes Krude <johannes.krude@comsys.rwth-aachen.de>
Date: Tue, 31 May 2022 23:57:18 +0200
Subject: [PATCH] document custom home view (#21066)

Co-authored-by: Travis Ralston <travisr@matrix.org>
---
 docs/config.md      |  2 +-
 docs/custom-home.md | 65 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 66 insertions(+), 1 deletion(-)
 create mode 100644 docs/custom-home.md

diff --git a/docs/config.md b/docs/config.md
index 74a4a690d8..ee0d54763f 100644
--- a/docs/config.md
+++ b/docs/config.md
@@ -193,7 +193,7 @@ Starting with `branding`, the following subproperties are available:
    `welcome.html` that ships with Element will be used instead.
 2. `home_url`: A URL to an HTML page to show within the app as the "home" page. When the app doesn't have a room/screen to
    show the user, it will use the home page instead. The home page is additionally accessible from the user menu. By default,
-   no home page is set and therefore a hardcoded landing screen is used.
+   no home page is set and therefore a hardcoded landing screen is used. More documentation and examples are [here](./custom-home.md).
 3. `login_for_welcome`: When `true` (default `false`), the app will use the login form as a welcome page instead of the welcome
    page itself. This disables use of `welcome_url` and all welcome page functionality.
 
diff --git a/docs/custom-home.md b/docs/custom-home.md
new file mode 100644
index 0000000000..a179c6c7d0
--- /dev/null
+++ b/docs/custom-home.md
@@ -0,0 +1,65 @@
+# Custom Home Page
+
+The home page is shown whenever the user is logged in, but no room is selected.
+A custom `home.html` replacing the default home page can be configured either in `.well-known/matrix/client` or `config.json`.
+Such a custom home page can be used to communicate helpful information and important rules to the users.
+
+## Configuration
+
+To provide a custom home page for all element-web/desktop users of a homeserver, include the following in `.well-known/matrix/client`:
+
+```
+{
+    "io.element.embedded_pages": {
+        "home_url": "https://example.org/home.html"
+    }
+}
+```
+
+The home page can be overridden in `config.json` to provide all users of an element-web installation with the same experience:
+
+```
+{
+    "embeddedPages": {
+        "homeUrl": "https://example.org/home.html"
+    }
+}
+```
+
+
+## `home.html` Example
+
+The following is a simple example for a custom `home.html`:
+
+```
+<style type="text/css">
+	.tos {
+		width: auto;
+		color: black;
+		background : #ffcccb;
+		font-weight: bold;
+	}
+</style>
+
+<h1>The example.org Matrix Server</h1>
+
+<div class="tos">
+	<p>Behave appropriately.</p>
+</div>
+
+<h2>Start Chatting</h2>
+<ul>
+	<li><a href="#/dm">Send a Direct Message</a></li>
+	<li><a href="#/directory">Explore Public Rooms</a></li>
+	<li><a href="#/new">Create a Group Chat</a></li>
+</ul>
+```
+
+When choosing colors, be aware that the home page may be displayed in either light or dark mode.
+
+It may be needed to set CORS headers for the `home.html` to enable element-desktop to fetch it, with e.g., the following nginx config:
+
+```
+add_header Access-Control-Allow-Origin *;
+```
+