diff --git a/docs/config.md b/docs/config.md index 74a4a690d89..ee0d54763fc 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 00000000000..a179c6c7d08 --- /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`: + +``` + + +

The example.org Matrix Server

+ +
+

Behave appropriately.

+
+ +

Start Chatting

+ +``` + +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 *; +``` +