Annotate certain features as optional/advanced

We've had some people get confused into installing
Matrix Corporal and having pain with that.

With this documentation change, we try to make it clearer
that it's an advanced feature not to be touched unless
you know what you're doing.

On a similar note, we also make sure other things are properly
labeled as "(optional)" and/or "(advanced)".

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

@@ -1,11 +1,12 @@
-# Setting up Mautrix Telegram
+# Setting up Mautrix Telegram (optional)
 
 The playbook can install and configure [mautrix-telegram](https://github.com/tulir/mautrix-telegram) for you.
 
 See the project's [documentation](https://github.com/tulir/mautrix-telegram/wiki#usage) 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` and then use the following playbook configuration:
-```
+
+```yaml
 matrix_mautrix_telegram_enabled: true
 matrix_mautrix_telegram_api_id: YOUR_TELEGRAM_APP_ID
 matrix_mautrix_telegram_api_hash: YOUR_TELEGRAM_API_HASH

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

@@ -1,11 +1,12 @@
-# Setting up Mautrix Whatsapp
+# Setting up Mautrix Whatsapp (optional)
 
 The playbook can install and configure [mautrix-whatsapp](https://github.com/tulir/mautrix-whatsapp) for you.
 
 See the project's [documentation](https://github.com/tulir/mautrix-whatsapp/wiki) to learn what it does and why it might be useful to you.
 
 Use the following playbook configuration:
-```
+
+```yaml
 matrix_mautrix_whatsapp_enabled: true
 ```
 

docs/configuring-playbook-federation.md

@@ -1,4 +1,4 @@
-# Controlling Matrix federation
+# Controlling Matrix federation (optional)
 
 By default, your server federates with the whole Matrix network.
 That is, people on your server can communicate with people on any other Matrix server.

docs/configuring-playbook-matrix-corporal.md

@@ -1,7 +1,14 @@
-# Setting up Matrix Corporal
+# Setting up Matrix Corporal (optional, advanced)
+
+-------------------------------------
+
+**WARNING**: This is an advanced feature! It requires prior experience with Matrix and a specific need for using [Matrix Corporal](https://github.com/devture/matrix-corporal). If you're unsure whether you have such a need, you most likely don't.
+
+-------------------------------------
 
 The playbook can install and configure [matrix-corporal](https://github.com/devture/matrix-corporal) for you.
 
+In short, it's a sort of automation and firewalling service, which is helpful if you're instaling Matrix services in a controlled corporate environment.
 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'd need to also [set up the Shared Secret Auth password provider module](configuring-playbook-shared-secret-auth.md).

docs/configuring-playbook-own-webserver.md

@@ -1,4 +1,4 @@
-# Using your own webserver, instead of this playbook's nginx proxy (optional)
+# Using your own webserver, instead of this playbook's nginx proxy (optional, advanced)
 
 By default, this playbook installs its own nginx webserver (in a Docker container) which listens on ports 80 and 443.
 If that's alright, you can skip this.
@@ -12,7 +12,7 @@ All it takes is:
 
 2) editing your configuration file (`inventory/matrix.<your-domain>/vars.yml`):
 
-```
+```yaml
 matrix_nginx_proxy_enabled: false
 ```
 

docs/configuring-playbook-rest-auth.md

@@ -1,4 +1,4 @@
-# Setting up the REST authentication password provider module
+# Setting up the REST authentication password provider module (optional, advanced)
 
 The playbook can install and configure [matrix-synapse-rest-auth](https://github.com/kamax-io/matrix-synapse-rest-auth) for you.
 

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

@@ -1,4 +1,4 @@
-# Setting up the Shared Secret Auth password provider module
+# Setting up the Shared Secret Auth password provider module (optional, advanced)
 
 The playbook can install and configure [matrix-synapse-shared-secret-auth](https://github.com/devture/matrix-synapse-shared-secret-auth) for you.
 

docs/configuring-playbook-telemetry.md

@@ -1,4 +1,4 @@
-# Enabling Telemetry for your Matrix server
+# Enabling Telemetry for your Matrix server (optional)
 
 By default, this playbook configures your Matrix homeserver to not send any telemetry data anywhere.
 

docs/configuring-playbook.md

@@ -35,13 +35,13 @@ When you're done with all the configuration you'd like to do, continue with [Ins
 
 - [Adjusting mxisd Identity Server configuration](configuring-playbook-mxisd.md) (optional)
 
-- [Using your own webserver, instead of this playbook's nginx proxy](configuring-playbook-own-webserver.md) (optional)
+- [Using your own webserver, instead of this playbook's nginx proxy](configuring-playbook-own-webserver.md) (optional, advanced)
 
-- [Setting up the REST authentication password provider module](configuring-playbook-rest-auth.md) (optional)
+- [Setting up the REST authentication password provider module](configuring-playbook-rest-auth.md) (optional, advanced)
 
-- [Setting up the Shared Secret Auth password provider module](configuring-playbook-shared-secret-auth.md) (optional)
+- [Setting up the Shared Secret Auth password provider module](configuring-playbook-shared-secret-auth.md) (optional, advanced)
 
-- [Setting up Matrix Corporal](configuring-playbook-matrix-corporal.md) (optional)
+- [Setting up Matrix Corporal](configuring-playbook-matrix-corporal.md) (optional, advanced)
 
 - [Setting up Mautrix Telegram bridging](configuring-playbook-bridge-mautrix-telegram.md) (optional)