riot-web/docs/custom-home.md

64 lines
1.6 KiB
Markdown
Raw Normal View History

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