Use common expression on documentation regarding playbook configuration

Overall the playbook uses the expression "Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:" with the heading "Adjusting the playbook configuration" for sections to explain what to be added as variables

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

docs/configuring-captcha.md

@@ -16,7 +16,7 @@ Must be a reCAPTCHA **v2** key using the "I'm not a robot" Checkbox option
 
 ### Setting ReCaptcha keys
 
-Once registered as above, set the following values:
+Once registered as above, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 ```yaml
 # for Synapse

docs/configuring-playbook-alertmanager-receiver.md

@@ -8,8 +8,9 @@ At the moment, **setting up this service's bot requires some manual actions** as
 
 This service is meant to be used with an external [Alertmanager](https://prometheus.io/docs/alerting/latest/alertmanager/) instance. It's **not** meant to be integrated with the [Prometheus & Grafana stack](./configuring-playbook-prometheus-grafana.md) installed by this playbook, because the Alertmanager component is not installed by it.
 
+## Adjusting the playbook configuration
 
-## Configuration
+Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 ```yml
 matrix_alertmanager_receiver_enabled: true

docs/configuring-playbook-appservice-double-puppet.md

@@ -6,7 +6,9 @@ This is useful for performing [double-puppeting](https://docs.mau.fi/bridges/gen
 
 Previously, bridges supported performing [double-puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) with the help of the [Shared Secret Auth password provider module](./configuring-playbook-shared-secret-auth.md), but this old and hacky solution has been superseded by this Appservice Double Puppet method.
 
-To enable the Appservice Double Puppet service, adjust your `vars.yml` configuration like this and [re-run the playbook](./installing.md) (`just install-all`):
+## Adjusting the playbook configuration
+
+To enable the Appservice Double Puppet service, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 ```yml
 matrix_appservice_double_puppet_enabled: true

docs/configuring-playbook-base-domain-serving.md

@@ -14,7 +14,7 @@ Usually, there are 2 options:
 
 This documentation page tells you how to do the latter. With some easy changes, we make it possible to serve the base domain from the Matrix server via the integrated webserver.
 
-Just **adjust your DNS records**, so that your base domain is pointed to the Matrix server's IP address (using a DNS `A` record) **and then use the following configuration**:
+Just **adjust your DNS records**, so that your base domain is pointed to the Matrix server's IP address (using a DNS `A` record) **and then add the following configuration** to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 ```yaml
 matrix_static_files_container_labels_base_domain_enabled: true

docs/configuring-playbook-bridge-appservice-irc.md

@@ -6,7 +6,9 @@ The playbook can install and configure the [matrix-appservice-irc](https://githu
 
 See the project's [documentation](https://github.com/matrix-org/matrix-appservice-irc/blob/master/HOWTO.md) to learn what it does and why it might be useful to you.
 
-You'll need to use the following playbook configuration:
+## Adjusting the playbook configuration
+
+To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 ```yaml
 matrix_appservice_irc_enabled: true

docs/configuring-playbook-bridge-appservice-kakaotalk.md

@@ -9,7 +9,7 @@ See the project's [documentation](https://src.miscworks.net/fair/matrix-appservi
 
 ## Installing
 
-To enable the bridge, add this to your `vars.yml` file:
+To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 ```yaml
 matrix_appservice_kakaotalk_enabled: true

docs/configuring-playbook-bridge-beeper-linkedin.md

@@ -4,6 +4,10 @@ The playbook can install and configure [beeper-linkedin](https://github.com/beep
 
 See the project's [documentation](https://github.com/beeper/linkedin/blob/master/README.md) to learn what it does and why it might be useful to you.
 
+## Adjusting the playbook configuration
+
+To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
+
 ```yaml
 matrix_beeper_linkedin_enabled: true
 ```

docs/configuring-playbook-bridge-go-skype-bridge.md

@@ -5,9 +5,9 @@ The playbook can install and configure
 
 See the project page to learn what it does and why it might be useful to you.
 
-To enable the [Skype](https://www.skype.com/) bridge just use the following
-playbook configuration:
+## Adjusting the playbook configuration
 
+To enable the [Skype](https://www.skype.com/) bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 ```yaml
 matrix_go_skype_bridge_enabled: true

docs/configuring-playbook-bridge-matrix-bridge-sms.md

@@ -6,15 +6,15 @@ See the project page to learn what it does and why it might be useful to you.
 
 **The bridge uses [android-sms-gateway-server](https://github.com/RebekkaMa/android-sms-gateway-server). You need to configure it first.**
 
-To enable the bridge just use the following
-playbook configuration:
+## Adjusting the playbook configuration
 
+To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 ```yaml
 matrix_sms_bridge_enabled: true
 
 # (optional but recommended) a room id to a default room
-matrix_sms_bridge_default_room: "" 
+matrix_sms_bridge_default_room: ""
 
 # (optional but recommended) configure your server location
 matrix_sms_bridge_default_region: DE

docs/configuring-playbook-bridge-mautrix-discord.md

@@ -15,9 +15,9 @@ There are 2 ways to login to discord using this bridge, either by [scanning a QR
 
 If this is a dealbreaker for you, consider using one of the other Discord bridges supported by the playbook: [mx-puppet-discord](configuring-playbook-bridge-mx-puppet-discord.md) or [matrix-appservice-discord](configuring-playbook-bridge-appservice-discord.md). These come with their own complexity and limitations, however, so we recommend that you proceed with this one if possible.
 
-## Installing
+## Adjusting the playbook configuration
 
-To enable the bridge, add this to your `vars.yml` file:
+To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 ```yaml
 matrix_mautrix_discord_enabled: true

docs/configuring-playbook-bridge-mautrix-facebook.md

@@ -6,6 +6,10 @@ The playbook can install and configure [mautrix-facebook](https://github.com/mau
 
 See the project's [documentation](https://github.com/mautrix/facebook/blob/master/ROADMAP.md) to learn what it does and why it might be useful to you.
 
+## Adjusting the playbook configuration
+
+To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
+
 ```yaml
 matrix_mautrix_facebook_enabled: true
 ```

docs/configuring-playbook-bridge-mautrix-gmessages.md

@@ -4,7 +4,9 @@ The playbook can install and configure [mautrix-gmessages](https://github.com/ma
 
 See the project's [documentation](https://docs.mau.fi/bridges/go/gmessages/index.html) to learn what it does and why it might be useful to you.
 
-Use the following playbook configuration:
+## Adjusting the playbook configuration
+
+To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 ```yaml
 matrix_mautrix_gmessages_enabled: true

docs/configuring-playbook-bridge-mautrix-googlechat.md

@@ -4,8 +4,9 @@ The playbook can install and configure [mautrix-googlechat](https://github.com/m
 
 See the project's [documentation](https://docs.mau.fi/bridges/python/googlechat/index.html) to learn what it does and why it might be useful to you.
 
-To enable the [Google Chat](https://chat.google.com/) bridge just use the following playbook configuration:
+## Adjusting the playbook configuration
 
+To enable the [Google Chat](https://chat.google.com/) bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 ```yaml
 matrix_mautrix_googlechat_enabled: true
@@ -51,4 +52,3 @@ Once logged in, recent chats should show up as new conversations automatically.
 You can learn more about authentication from the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/python/googlechat/authentication.html).
 
 After successfully enabling bridging, you may wish to [set up Double Puppeting](#set-up-double-puppeting), if you haven't already done so.
-

docs/configuring-playbook-bridge-mautrix-hangouts.md

@@ -1,4 +1,4 @@
-# The [Mautrix Hangouts Bridge](https://mau.dev/mautrix/hangouts) is no longer maintained.  It has changed to a [Google Chat Bridge](https://github.com/mautrix/googlechat). Setup instructions for the Google Chat Bridge can be [found here](configuring-playbook-bridge-mautrix-googlechat.md). 
+# The [Mautrix Hangouts Bridge](https://mau.dev/mautrix/hangouts) is no longer maintained.  It has changed to a [Google Chat Bridge](https://github.com/mautrix/googlechat). Setup instructions for the Google Chat Bridge can be [found here](configuring-playbook-bridge-mautrix-googlechat.md).
 
 # Setting up Mautrix Hangouts (optional)
 
@@ -6,8 +6,9 @@ The playbook can install and configure [mautrix-hangouts](https://github.com/mau
 
 See the project's [documentation](https://docs.mau.fi/bridges/python/hangouts/index.html) to learn what it does and why it might be useful to you.
 
-To enable the [Google Hangouts](https://hangouts.google.com/) bridge just use the following playbook configuration:
+## Adjusting the playbook configuration
 
+To enable the [Google Hangouts](https://hangouts.google.com/) bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 ```yaml
 matrix_mautrix_hangouts_enabled: true
@@ -51,4 +52,3 @@ Once logged in, recent chats should show up as new conversations automatically.
 You can learn more about authentication from the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/python/hangouts/authentication.html).
 
 After successfully enabling bridging, you may wish to [set up Double Puppeting](#set-up-double-puppeting), if you haven't already done so.
-

docs/configuring-playbook-bridge-mautrix-instagram.md

@@ -6,9 +6,14 @@ The playbook can install and configure [mautrix-instagram](https://github.com/ma
 
 See the project's [documentation](https://docs.mau.fi/bridges/python/instagram/index.html) to learn what it does and why it might be useful to you.
 
+## Adjusting the playbook configuration
+
+To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
+
 ```yaml
 matrix_mautrix_instagram_enabled: true
 ```
+
 There are some additional things you may wish to configure about the bridge before you continue.
 
 Encryption support is off by default. If you would like to enable encryption, add the following to your `vars.yml` file:

docs/configuring-playbook-bridge-mautrix-meta-instagram.md

@@ -21,9 +21,9 @@ This would give you a list of portals and groups of portals you may purge. Proce
 Then, consider disabling the old bridge in your configuration, so it won't recreate the portals when you receive new messages.
 
 
-## Configuration
+## Adjusting the playbook configuration
 
-Most simply, you can enable the bridge with the following playbook configuration:
+To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 ```yaml
 matrix_mautrix_meta_instagram_enabled: true

docs/configuring-playbook-bridge-mautrix-meta-messenger.md

@@ -17,10 +17,9 @@ This would give you a list of portals and groups of portals you may purge. Proce
 
 Then, consider disabling the old bridge in your configuration, so it won't recreate the portals when you receive new messages.
 
+## Adjusting the playbook configuration
 
-## Configuration
-
-Most simply, you can enable the bridge with the following playbook configuration:
+To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 ```yaml
 matrix_mautrix_meta_messenger_enabled: true

docs/configuring-playbook-bridge-mautrix-signal.md

@@ -8,7 +8,9 @@ See the project's [documentation](https://docs.mau.fi/bridges/python/signal/inde
 
 **Note**: This revamped version of the [mautrix-signal (legacy)](configuring-playbook-bridge-mautrix-signal.md) may increase the CPU usage of your homeserver.
 
-Use the following playbook configuration:
+## Adjusting the playbook configuration
+
+To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 ```yaml
 matrix_mautrix_signal_enabled: true

docs/configuring-playbook-bridge-mautrix-slack.md

@@ -18,9 +18,9 @@ For using this bridge, you would need to authenticate by **providing your userna
 Note that neither of these methods are officially supported by Slack. [matrix-appservice-slack](configuring-playbook-bridge-appservice-slack.md) uses a Slack bot account which is the only officially supported method for bridging a Slack channel.
 
 
-## Installing
+## Adjusting the playbook configuration
 
-To enable the bridge, add this to your `vars.yml` file:
+To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 ```yaml
 matrix_mautrix_slack_enabled: true

docs/configuring-playbook-bridge-mautrix-telegram.md

@@ -4,7 +4,9 @@ The playbook can install and configure [mautrix-telegram](https://github.com/mau
 
 See the project's [documentation](https://docs.mau.fi/bridges/python/telegram/index.html) to learn what it does and why it might be useful to you.
 
-You'll need to obtain API keys from [https://my.telegram.org/apps](https://my.telegram.org/apps) and then use the following playbook configuration:
+## Adjusting the playbook configuration
+
+You'll need to obtain API keys from [https://my.telegram.org/apps](https://my.telegram.org/apps) and then add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 ```yaml
 matrix_mautrix_telegram_enabled: true
@@ -41,7 +43,7 @@ When using this method, **each user** that wishes to enable Double Puppeting nee
 
 You then need to start a chat with `@telegrambot:YOUR_DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
 
-If you want to use the relay-bot feature ([relay bot documentation](https://docs.mau.fi/bridges/python/telegram/relay-bot.html)), which allows anonymous user to chat with telegram users, use the following additional playbook configuration:
+If you want to use the relay-bot feature ([relay bot documentation](https://docs.mau.fi/bridges/python/telegram/relay-bot.html)), which allows anonymous user to chat with telegram users, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 ```yaml
 matrix_mautrix_telegram_bot_token: YOUR_TELEGRAM_BOT_TOKEN

docs/configuring-playbook-bridge-mautrix-twitter.md

@@ -6,6 +6,10 @@ The playbook can install and configure [mautrix-twitter](https://github.com/maut
 
 See the project's [documentation](https://github.com/mautrix/twitter) to learn what it does and why it might be useful to you.
 
+## Adjusting the playbook configuration
+
+To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
+
 ```yaml
 matrix_mautrix_twitter_enabled: true
 ```

docs/configuring-playbook-bridge-mautrix-whatsapp.md

@@ -4,11 +4,14 @@ The playbook can install and configure [mautrix-whatsapp](https://github.com/mau
 
 See the project's [documentation](https://docs.mau.fi/bridges/go/whatsapp/index.html) to learn what it does and why it might be useful to you.
 
-Use the following playbook configuration:
+## Adjusting the playbook configuration
+
+To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 ```yaml
 matrix_mautrix_whatsapp_enabled: true
 ```
+
 Whatsapp multidevice beta is required, now it is enough if Whatsapp is connected to the Internet every 2 weeks.
 
 The relay bot functionality is off by default. If you would like to enable the relay bot, add the following to your `vars.yml` file:

docs/configuring-playbook-bridge-mautrix-wsproxy.md

@@ -10,10 +10,9 @@ See the project's [documentation](https://github.com/mautrix/wsproxy#readme) to
 You need to create a `wsproxy.DOMAIN` DNS record pointing to your Matrix server (a `CNAME` pointing to `matrix.DOMAIN`) to use wsproxy.
 The hostname is configurable via a `matrix_mautrix_wsproxy_hostname` variable.
 
+## Adjusting the playbook configuration
 
-## Configuration
-
-Use the following playbook configuration:
+To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 ```yaml
 matrix_mautrix_wsproxy_enabled: true

docs/configuring-playbook-bridge-mx-puppet-discord.md

@@ -11,9 +11,9 @@ See the project page to learn what it does and why it might be useful to you.
 
 **Note**: we actually use the [Beeper](https://www.beeper.com/)-maintained [fork of mx-puppet-discord](https://gitlab.com/beeper/mx-puppet-monorepo), because `matrix-discord/mx-puppet-discord` is a low-quality and poorly maintained project.
 
-To enable the [Discord](https://discordapp.com/) bridge just use the following
-playbook configuration:
+## Adjusting the playbook configuration
 
+To enable the [Discord](https://discordapp.com/) bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 ```yaml
 matrix_mx_puppet_discord_enabled: true

docs/configuring-playbook-bridge-mx-puppet-groupme.md

@@ -5,9 +5,9 @@ The playbook can install and configure
 
 See the project page to learn what it does and why it might be useful to you.
 
-To enable the [GroupMe](https://groupme.com/) bridge just use the following
-playbook configuration:
+## Adjusting the playbook configuration
 
+To enable the [GroupMe](https://groupme.com/) bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 ```yaml
 matrix_mx_puppet_groupme_enabled: true

docs/configuring-playbook-bridge-mx-puppet-instagram.md

@@ -5,9 +5,9 @@ The playbook can install and configure
 
 This allows you to bridge Instagram DirectMessages into Matrix.
 
-To enable the [Instagram](https://www.instagram.com/) bridge just use the following
-playbook configuration:
+## Adjusting the playbook configuration
 
+To enable the [Instagram](https://www.instagram.com/) bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 ```yaml
 matrix_mx_puppet_instagram_enabled: true
@@ -33,4 +33,3 @@ For double-puppeting, you probably want to issue these commands:
 If you are linking only one Instagram account, your `$puppetId` is probably 1, but use the `list` command find out.
 
 The `help` command shows which commands are available, though at the time of writing, not every command is fully implemented.
-

docs/configuring-playbook-bridge-mx-puppet-slack.md

@@ -8,25 +8,28 @@ The playbook can install and configure [Beeper](https://www.beeper.com/)-maintai
 
 See the project page to learn what it does and why it might be useful to you.
 
-## Setup
+## Prerequisite
 
-To enable the [Slack](https://slack.com/) bridge:
+Follow the [OAuth credentials](https://github.com/Sorunome/mx-puppet-slack#option-2-oauth) instructions to create a new Slack app, setting the redirect URL to `https://matrix.DOMAIN/slack/oauth`.
 
-1. Follow the
-   [OAuth credentials](https://github.com/Sorunome/mx-puppet-slack#option-2-oauth)
-   instructions to create a new Slack app, setting the redirect URL to
-   `https://matrix.YOUR_DOMAIN/slack/oauth`.
-2. Update your `vars.yml` with the following:
-    ```yaml
-    matrix_mx_puppet_slack_enabled: true
-    # Client ID must be quoted so YAML does not parse it as a float.
-    matrix_mx_puppet_slack_oauth_client_id: "<SLACK_APP_CLIENT_ID>"
-    matrix_mx_puppet_slack_oauth_client_secret: "<SLACK_APP_CLIENT_SECRET>"
-    ```
-3. Run playbooks with `setup-all` and `start` tags:
-    ```
-    ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
-    ```
+## Adjusting the playbook configuration
+
+To enable the [Slack](https://slack.com/) bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
+
+```yaml
+matrix_mx_puppet_slack_enabled: true
+# Client ID must be quoted so YAML does not parse it as a float.
+matrix_mx_puppet_slack_oauth_client_id: "<SLACK_APP_CLIENT_ID>"
+matrix_mx_puppet_slack_oauth_client_secret: "<SLACK_APP_CLIENT_SECRET>"
+```
+
+## Installing
+
+After configuring the playbook, run the [installation](installing.md) command:
+
+```
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+```
 
 ## Usage
 

docs/configuring-playbook-bridge-mx-puppet-steam.md

@@ -5,9 +5,9 @@ The playbook can install and configure
 
 See the project page to learn what it does and why it might be useful to you.
 
-To enable the [Steam](https://steampowered.com/) bridge just use the following
-playbook configuration:
+## Adjusting the playbook configuration
 
+To enable the [Steam](https://steampowered.com/) bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 ```yaml
 matrix_mx_puppet_steam_enabled: true

docs/configuring-playbook-bridge-mx-puppet-twitter.md

@@ -7,8 +7,13 @@ The playbook can install and configure
 
 See the project page to learn what it does and why it might be useful to you.
 
-To enable the [Twitter](https://twitter.com) bridge, make an app on [developer.twitter.com](https://developer.twitter.com/en/apps)
-and fill out the following playbook configuration.
+## Prerequisite
+
+Make an app on [developer.twitter.com](https://developer.twitter.com/en/apps).
+
+## Adjusting the playbook configuration
+
+To enable the [Twitter](https://twitter.com) bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 ```yaml
 matrix_mx_puppet_twitter_enabled: true

docs/configuring-playbook-bridge-wechat.md

@@ -4,7 +4,9 @@ The playbook can install and configure the [matrix-wechat](https://github.com/du
 
 See the project page to learn what it does and why it might be useful to you.
 
-To enable the bridge, use the following playbook configuration and re-run the playbook's [installation](./installing.md) procedure:
+## Adjusting the playbook configuration
+
+To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 ```yaml
 matrix_wechat_enabled: true

docs/configuring-playbook-email.md

@@ -17,8 +17,7 @@ No matter whether you send email directly (the default) or you relay email throu
 
 ## Relaying email through another SMTP server
 
-If you'd like to relay email through another SMTP server, feel free to redefine a few playbook variables.
-Example:
+If you'd like to relay email through another SMTP server, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs):
 
 ```yaml
 exim_relay_sender_address: "another.sender@example.com"

docs/configuring-playbook-email2matrix.md

@@ -43,9 +43,9 @@ You'll need the room id when doing [Configuration](#configuration) below.
 
 In order for the sender user created above to be able to send messages to the room, we'll need to obtain an access token for it. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
 
-## Configuration
+## Adjusting the playbook configuration
 
-After doing the preparation steps above, adjust your `inventory/host_vars/matrix.DOMAIN/vars.yml` configuration like this:
+After doing the preparation steps above, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs):
 
 ```yaml
 matrix_email2matrix_enabled: true

docs/configuring-playbook-etherpad.md

@@ -28,9 +28,9 @@ Once you've decided on the domain and path, **you may need to adjust your DNS**
 If you've decided to reuse the `matrix.` domain, you won't need to do any extra DNS configuration.
 
 
-## Installing
+## Adjusting the playbook configuration
 
-[Etherpad](https://etherpad.org) installation is disabled by default. You can enable it in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
+[Etherpad](https://etherpad.org) installation is disabled by default. To enable Etherpad, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 ```yaml
 etherpad_enabled: true

docs/configuring-playbook-external-postgres.md

@@ -7,7 +7,7 @@ If you'd like to use an external PostgreSQL server that you manage, you can edit
 
 **NOTE**: using **an external Postgres server is currently [not very seamless](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/1682#issuecomment-1061461683) when it comes to enabling various other playbook services** - you will need to create a new database/credentials for each service and to point each service to its corresponding database using custom `vars.yml` configuration. **For the best experience with the playbook, stick to using the integrated Postgres server**.
 
-If you'd like to use an external Postgres server, use a custom `vars.yml` configuration like this:
+If you'd like to use an external Postgres server, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs):
 
 ```yaml
 postgres_enabled: false

docs/configuring-playbook-federation.md

@@ -6,7 +6,7 @@ That is, people on your server can communicate with people on any other Matrix s
 
 ## Federating only with select servers
 
-To make your server only federate with servers of your choosing, add this to your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
+To make your server only federate with servers of your choosing, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs):
 
 ```yaml
 matrix_synapse_federation_domain_whitelist:

docs/configuring-playbook-jitsi.md

@@ -19,7 +19,7 @@ You may also need to open the following ports to your server:
 
 ## Installation
 
-Add this to your `inventory/host_vars/matrix.DOMAIN/vars.yml` configuration:
+Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 ```yaml
 jitsi_enabled: true

docs/configuring-playbook-ldap-auth.md

@@ -4,11 +4,11 @@ The playbook can install and configure the [matrix-synapse-ldap3](https://github
 
 See that project's documentation to learn what it does and why it might be useful to you.
 
-If you decide that you'd like to let this playbook install it for you, you need some configuration like this:
+If you decide that you'd like to let this playbook install it for you, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs):
 
 ```yaml
 matrix_synapse_ext_password_provider_ldap_enabled: true
-matrix_synapse_ext_password_provider_ldap_uri: 
+matrix_synapse_ext_password_provider_ldap_uri:
   - "ldap://ldap-01.mydomain.tld:389"
   - "ldap://ldap-02.mydomain.tld:389"
 matrix_synapse_ext_password_provider_ldap_start_tls: true

docs/configuring-playbook-ma1sd.md

@@ -10,14 +10,15 @@ This server is private by default, potentially at the expense of user discoverab
 
 **Note**: enabling ma1sd, means that the `openid` API endpoints will be exposed on the Matrix Federation port (usually `8448`), even if [federation](configuring-playbook-federation.md) is disabled. It's something to be aware of, especially in terms of firewall whitelisting (make sure port `8448` is accessible).
 
-To enable ma1sd, use the following additional configuration in your `vars.yml` file:
+## Adjusting the playbook configuration
+
+To enable ma1sd, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 ```yaml
 matrix_ma1sd_enabled: true
 ```
 
-
-## Matrix.org lookup forwarding
+### Matrix.org lookup forwarding
 
 To ensure maximum discovery, you can make your identity server also forward lookups to the central matrix.org Identity server (at the cost of potentially leaking all your contacts information).
 
@@ -29,8 +30,7 @@ Enabling matrix.org forwarding can happen with the following configuration:
 matrix_ma1sd_matrixorg_forwarding_enabled: true
 ```
 
-
-## Customizing email templates
+### Customizing email templates
 
 If you'd like to change the default email templates used by ma1sd, take a look at the `matrix_ma1sd_threepid_medium_email_custom_` variables
 (in the `roles/custom/matrix-ma1sd/defaults/main.yml` file.

docs/configuring-playbook-matrix-corporal.md

@@ -16,9 +16,9 @@ If you decide that you'd like to let this playbook install it for you, you'd nee
 - (optional, but encouraged) [set up the REST authentication password provider module](configuring-playbook-rest-auth.md)
 
 
-## Playbook configuration
+## Adjusting the playbook configuration
 
-You would then need some configuration like this:
+Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs):
 
 ```yaml
 # The Shared Secret Auth password provider module is required for Corporal to work.

docs/configuring-playbook-mautrix-bridges.md

@@ -5,24 +5,23 @@ This is a common guide for configuring mautrix bridges.
 
 You can see each bridge's features at in the `ROADMAP.md` file in its corresponding [mautrix](https://github.com/mautrix) repository.
 
-To enable a bridge add:
+## Adjusting the playbook configuration
 
+To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 ```yaml
 # Replace SERVICENAME with one of: twitter, facebook, instagram, ..
 matrix_mautrix_SERVICENAME_enabled: true
 ```
 
-to your `vars.yml`
-
 There are some additional things you may wish to configure about the bridge before you continue. Each bridge may have additional requirements besides `_enabled: true`. For example, the mautrix-telegram bridge (our documentation page about it is [here](configuring-playbook-bridge-mautrix-telegram.md)) requires the `matrix_mautrix_telegram_api_id` and `matrix_mautrix_telegram_api_hash` variables to be defined. Refer to each bridge's individual documentation page for details about enabling bridges.
 
-You can add
+To **configure a user as an administrator for all bridges**, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 ```yaml
 matrix_admin: "@YOUR_USERNAME:{{ matrix_domain }}"
 ```
-to `vars.yml` to **configure a user as an administrator for all bridges**.
+
 **Alternatively** (more verbose, but allows multiple admins to be configured), you can do the same on a per-bridge basis with:
 
 ```yaml
@@ -34,7 +33,7 @@ matrix_mautrix_SERVICENAME_configuration_extension_yaml: |
 
 ## encryption
 
-Encryption support is off by default. If you would like to enable encryption, add the following to your `vars.yml` file:
+Encryption support is off by default. If you would like to enable encryption, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 **for all bridges with encryption support**:
 
@@ -52,7 +51,7 @@ matrix_mautrix_SERVICENAME_bridge_encryption_default: true
 
 ## relay mode
 
-Relay mode is off by default. If you would like to enable relay mode, add the following to your `vars.yml` file:
+Relay mode is off by default. If you would like to enable relay mode, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 **for all bridges with relay mode support**:
 

docs/configuring-playbook-own-webserver.md

@@ -16,7 +16,7 @@ There are 2 ways to use Traefik with this playbook, as described below.
 
 ### Traefik managed by the playbook
 
-To have the playbook install and use Traefik, use configuration like this (as seen in `examples/vars.yml`):
+To have the playbook install and use Traefik, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 ```yaml
 matrix_playbook_reverse_proxy_type: playbook-managed-traefik

docs/configuring-playbook-postgres-backup.md

@@ -7,7 +7,7 @@ For a more complete backup solution (one that includes not only Postgres, but al
 
 ## Adjusting the playbook configuration
 
-Minimal working configuration (`inventory/host_vars/matrix.DOMAIN/vars.yml`) to enable Postgres backup:
+To enable Postgres backup, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 ```yaml
 postgres_backup_enabled: true

docs/configuring-playbook-prometheus-nginxlog.md

@@ -14,7 +14,7 @@ If your setup includes [Grafana](./configuring-playbook-prometheus-grafana.md),
 
 ## Configuration
 
-You can enable this role by adding the following settings in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
+Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 ```yaml
 matrix_prometheus_nginxlog_exporter_enabled: true
@@ -50,5 +50,3 @@ You can either use `matrix_prometheus_nginxlog_exporter_metrics_proxying_enabled
 Whichever way you go with, this service will expose its metrics endpoint **without password-protection** at `https://matrix.DOMAIN/metrics/nginxlog` by default.
 
 For password-protection, use (`matrix_metrics_exposure_http_basic_auth_enabled` and `matrix_metrics_exposure_http_basic_auth_users`) or (`matrix_prometheus_nginxlog_exporter_container_labels_metrics_middleware_basic_auth_enabled` and `matrix_prometheus_nginxlog_exporter_container_labels_metrics_middleware_basic_auth_users`).
-
-

docs/configuring-playbook-prometheus-postgres.md

@@ -2,8 +2,9 @@
 
 Expanding on the metrics exposed by the [synapse exporter and the node exporter](configuring-playbook-prometheus-grafana.md), the playbook enables the [postgres exporter](https://github.com/prometheus-community/postgres_exporter) that exposes more detailed information about what's happening on your postgres database.
 
-You can enable this with the following settings in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
+## Adjusting the playbook configuration
 
+To enable the postgres exporter, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 ```yaml
 prometheus_postgres_exporter_enabled: true
@@ -22,4 +23,3 @@ Name | Description
 ## More information
 
 - [The PostgresSQL dashboard](https://grafana.com/grafana/dashboards/9628) (generic postgres dashboard)
-

docs/configuring-playbook-rest-auth.md

@@ -4,7 +4,9 @@ The playbook can install and configure [matrix-synapse-rest-auth](https://github
 
 See that project's documentation to learn what it does and why it might be useful to you.
 
-If you decide that you'd like to let this playbook install it for you, you need some configuration like this:
+## Adjusting the playbook configuration
+
+Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs):
 
 ```yaml
 matrix_synapse_ext_password_provider_rest_auth_enabled: true
@@ -14,7 +16,6 @@ matrix_synapse_ext_password_provider_rest_auth_registration_profile_name_autofil
 matrix_synapse_ext_password_provider_rest_auth_login_profile_name_autofill: false
 ```
 
-
 ## Authenticating only using a password provider
 
 If you wish for users to **authenticate only against configured password providers** (like this one), **without consulting Synapse's local database**, feel free to disable it:

docs/configuring-playbook-s3-goofys.md

@@ -9,10 +9,9 @@ Using a Goofys-backed media store works, but performance may not be ideal. If po
 
 If you'd like to move your locally-stored media store data to Amazon S3 (or another S3-compatible object store), we also provide some migration instructions below.
 
+## Adjusting the playbook configuration
 
-## Usage
-
-After [creating the S3 bucket and configuring it](configuring-playbook-s3.md#bucket-creation-and-security-configuration), you can proceed to configure Goofys in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
+After [creating the S3 bucket and configuring it](configuring-playbook-s3.md#bucket-creation-and-security-configuration), add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs):
 
 ```yaml
 matrix_s3_media_store_enabled: true

docs/configuring-playbook-shared-secret-auth.md

@@ -4,7 +4,9 @@ The playbook can install and configure [matrix-synapse-shared-secret-auth](https
 
 See that project's documentation to learn what it does and why it might be useful to you.
 
-If you decide that you'd like to let this playbook install it for you, you need some configuration (`inventory/host_vars/matrix.<your-domain>/vars.yml`) like this:
+## Adjusting the playbook configuration
+
+Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 ```yaml
 matrix_synapse_ext_password_provider_shared_secret_auth_enabled: true

docs/configuring-playbook-ssl-certificates.md

@@ -9,7 +9,7 @@ This guide is about using the integrated Traefik server and doesn't apply if you
 
 For testing purposes, you may wish to use staging certificates provide by Let's Encrypt.
 
-You can do this with the following configuration:
+Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 ```yaml
 traefik_config_certificatesResolvers_acme_use_staging: true
@@ -20,7 +20,7 @@ traefik_config_certificatesResolvers_acme_use_staging: true
 
 For testing or other purposes, you may wish to install services without SSL termination and have services exposed to `http://` instead of `https://`.
 
-You can do this with the following configuration:
+Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 ```yaml
 traefik_config_entrypoint_web_secure_enabled: false

docs/configuring-playbook-synapse-auto-accept-invite.md

@@ -10,7 +10,7 @@ In short, it automatically accepts room invites. You can specify that only 1:1 r
 
 ## Configuration
 
-If you decide that you'd like to let this playbook install the [synapse-auto-invite-accept](https://github.com/matrix-org/synapse-auto-accept-invite module for you, you need a configuration like this:
+If you decide that you'd like to let this playbook install the [synapse-auto-invite-accept](https://github.com/matrix-org/synapse-auto-accept-invite module for you, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 ```yaml
 matrix_synapse_ext_synapse_auto_accept_invite_enabled: true

docs/configuring-playbook-synapse-simple-antispam.md

@@ -5,7 +5,9 @@ The playbook can install and configure [synapse-simple-antispam](https://github.
 See that project's documentation to learn what it does and why it might be useful to you.
 In short, it lets you fight invite-spam by automatically blocking invitiations from a list of servers specified by you (blacklisting).
 
-If you decide that you'd like to let this playbook install it for you, you need some configuration like this:
+## Adjusting the playbook configuration
+
+Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file (adapt to your needs):
 
 ```yaml
 matrix_synapse_ext_spam_checker_synapse_simple_antispam_enabled: true

docs/configuring-playbook-synapse.md

@@ -22,7 +22,7 @@ Alternatively, **if there is no pre-defined variable** for a Synapse setting you
 
 To have Synapse gracefully handle thousands of users, worker support should be enabled. It factors out some homeserver tasks and spreads the load of incoming client and server-to-server traffic between multiple processes. More information can be found in the [official Synapse workers documentation](https://github.com/element-hq/synapse/blob/master/docs/workers.md) and [Tom Foster](https://github.com/tcpipuk)'s [Synapse homeserver guide](https://tcpipuk.github.io/synapse/index.html).
 
-To enable Synapse worker support, update your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
+To enable Synapse worker support, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 ```yaml
 matrix_synapse_workers_enabled: true

docs/configuring-playbook-telemetry.md

@@ -9,7 +9,7 @@ growth of the Matrix community, and helps to make Matrix a success.
 
 ## Enabling Telemetry
 
-If you'd like to **help by enabling submission of general usage statistics** for your homeserver, add this to your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
+If you'd like to **help by enabling submission of general usage statistics** for your homeserver, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 ```yaml
 matrix_synapse_report_stats: true # for synapse

docs/configuring-playbook-turn.md

@@ -7,7 +7,7 @@ By default, the Synapse chat server is configured, so that it points to the Cotu
 
 ## Disabling Coturn
 
-If, for some reason, you'd like to prevent the playbook from installing Coturn, you can use the following configuration:
+If, for some reason, you'd like to prevent the playbook from installing Coturn, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 ```yaml
 matrix_coturn_enabled: false

docs/configuring-playbook-user-verification-service.md

@@ -11,7 +11,7 @@ If the Jitsi server is also configured by this playbook, all plugging of variabl
 
 __Some general concepts of UVS may be helpful to understand the rest, so here they are:__
 
-UVS can be used to verify two claims: 
+UVS can be used to verify two claims:
 
 * (A) Whether a given OpenID token is valid for a given server and
 * (B) whether a user is member of a given room and the corresponding PowerLevel
@@ -31,7 +31,7 @@ In order to use UVS, an admin token for the configured homeserver must be suppli
 ## Enable
 
 [Matrix User Verification Service](https://github.com/matrix-org/matrix-user-verification-service) installation is disabled by default.
-You can enable it in your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`):
+To enable it, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 ```yaml
 matrix_user_verification_service_enabled: true
@@ -95,12 +95,12 @@ matrix_user_verification_service_uvs_pin_openid_verify_server_name: false
 
 in your host_vars.
 
-This will instruct UVS to verify the OpenID token against any domain given in a request. 
+This will instruct UVS to verify the OpenID token against any domain given in a request.
 Homeserver discovery is done via '.well-known/matrix/server' of the given domain.
 
 ## Installation
 
-After these variables have been set, please run the following command to re-run setup and to restart UVS:
+After these variables have been set, run the [installation](installing.md) command to restart UVS:
 
 ```
 ansible-playbook -i inventory/hosts setup.yml --tags=setup-matrix-user-verification-service,start
@@ -108,7 +108,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-matrix-user-verificat
 
 ## Logging
 
-The configuration variable `UVS_LOG_LEVEL` can be set to: 
+The configuration variable `UVS_LOG_LEVEL` can be set to:
 - warning
 - info
 - debug