docs: Minor adjustments

docs/content/config/account-management/overview.md

@@ -4,8 +4,6 @@
 
 **TODO:** `ACCOUNT_PROVISIONER` and supplementary pages referenced here.
 
-An email address should conform to the [expected syntax](https://en.wikipedia.org/wiki/Email_address#Syntax).
-
 !!! info
 
     In the DMS docs, there may be references to the sub-components of an address (`local-part@domain-part`).
@@ -21,9 +19,13 @@ The email address assigned to an account is relevant for:
     - `SPOOF_PROTECTION=1` restricts the sender address to the DMS account email address, unless additional sender addresses have been permitted via supported config.
     - `SPOOF_PROTECTION=0` allows DMS accounts to use any sender address, only a single DMS account is necessary to send mail with different sender addresses.
 
-!!! warning
+??? warning "Email address considerations"
 
-    Ensure that you avoid configuring email addresses with the [sub-address tag delimiter](#sub-addressing), otherwise opt-out of the sub-addressing feature.
+    An email address should conform to the standard [permitted charset and format](https://stackoverflow.com/questions/2049502/what-characters-are-allowed-in-an-email-address/2049510#2049510).
+
+    DMS has features that need to reserve special characters to work correctly. Ensure those characters are not present in email addresses you configure for DMS, or disable / opt-out of the feature.
+
+    - [Sub-addressing](#sub-addressing) is enabled by default with the _tag delimiter_ `+`. This can be configured, or be unset to opt-out.
 
 ### Aliases
 
@@ -42,9 +44,9 @@ Wildcard and need to alias each real account.. (no longer supported?)
 
 !!! info
 
-    [Subaddressing][wikipedia::subaddressing] (_aka Plus Addressing or Address Tags_) is a feature that allows you to receive mail to an address which includes a tag appended to the `local-part` of a valid account address.
+    [Subaddressing][wikipedia::subaddressing] (_aka **Plus Addressing** or **Address Tags**_) is a feature that allows you to receive mail to an address which includes a tag appended to the `local-part` of a valid account address.
 
-    - A subaddress has a tag delimiter (default: `+`), followed by the tag: `<local-part>+<tag>@<domain-part>`
+    - A subaddress has a tag delimiter (_default: `+`_), followed by the tag: `<local-part>+<tag>@<domain-part>`
     - The subaddress `user+github@example.com` would deliver mail to the same mailbox as `user@example.com`.
     - Tags are dynamic. Anything between the `+` and `@` is understood as the tag, no additional configuration required.
     - Only the first occurence of the tag delimiter is recognized. Any additional occurences become part of the tag value itself.
@@ -87,7 +89,6 @@ Wildcard and need to alias each real account.. (no longer supported?)
     - Applying the Postfix `main.cf` setting: [`recipient_delimiter = +`][postfix-docs::recipient-delimiter]
     - Dovecot has the equivalent setting set as `+` by default: [`recipient_delimiter = +`][dovecot-docs::config::recipient-delimiter]
 
-
 ### Quotas
 
 - `imap-quota` is enabled and allow clients to query their mailbox usage.

docs/content/config/account-management/provisioner/file.md

@@ -1,10 +1,10 @@
 ---
-title: 'Account Management | File Provisioner'
+title: 'Account Management | Provisioner (File)'
 ---
 
 ## Accounts
 
-**Config file:** `docker-data/dms/config/postfix-accounts.cf`.
+**Config file:** `docker-data/dms/config/postfix-accounts.cf`
 
 The best way to manage DMS accounts and related config files is through our `setup` CLI provided within the container.
 
@@ -16,32 +16,32 @@ The best way to manage DMS accounts and related config files is through our `set
     - Add an alias: `setup alias add <FROM ALIAS> <TO TARGET ADDRESS>`
     - Learn more about the available subcommands via: `setup help`
 
-    ```console
+    ```bash
-    # Spin up a basic DMS instance and then shells into the container to provision accounts:
+    # Starts a basic DMS instance and then shells into the container to use the `setup` CLI:
-    $ docker run --rm -itd --name dms --hostname mail.example.com ghcr.io/docker-mailserver/docker-mailserver:latest
+    docker run --rm -itd --name dms --hostname mail.example.com ghcr.io/docker-mailserver/docker-mailserver:latest
-    $ docker exec -it dms bash
+    docker exec -it dms bash
 
     # Create some accounts:
-    $ setup email add john.doe@example.com bad-password
+    setup email add john.doe@example.com bad-password
-    $ setup email add jane.doe@example.com bad-password
+    setup email add jane.doe@example.com bad-password
 
     # Create an alias:
-    $ setup alias add your-alias-here@example.com john.doe@example.com
+    setup alias add your-alias-here@example.com john.doe@example.com
     ```
 
 !!! info
 
-    The email address chosen will also represent the login username credential for mail clients.
+    Account creation will normalize the provided email address to lowercase, as DMS does not support multiple case-sensitive address variants.
 
-    Account creation will also normalize the provided address to lowercase, as DMS does not support multiple address variants relying on case-sensitivity.
+    The email address chosen will also represent the _login username_ credential for mail clients to authenticate with.
 
-### Quotas
+## Quotas
 
 **Config file:** `docker-data/dms/config/dovecot-quotas.cf`
 
 When the mailbox is deleted, the quota directive is deleted as well.
 
-### Aliases
+## Aliases
 
 **Config file:** `docker-data/dms/config/postfix-virtual.cf`
 

docs/content/config/account-management/provisioner/ldap.md

@@ -1,5 +1,5 @@
 ---
-title: 'Account Management | LDAP Provisioner'
+title: 'Account Management | Provisioner (LDAP)'
 ---
 
 ## Introduction

docs/content/config/account-management/supplementary/oauth2.md

@@ -6,7 +6,7 @@ title: 'Account Management | OAuth2 Support'
 
 !!! warning "This is only a supplement to the existing account provisioners"
 
-    Accounts must still be managed via the configured [`ACCOUNT_PROVISIONER`][env::account-provisioner] (FILE or LDAP).
+    Accounts must still be managed via the configured [`ACCOUNT_PROVISIONER`][env::account-provisioner] (`FILE` or `LDAP`).
 
     Reasoning for this can be found in [#3480][gh-pr::oauth2]. Future iterations on this feature may allow it to become a full account provisioner.
 
@@ -15,13 +15,13 @@ title: 'Account Management | OAuth2 Support'
 
 The present OAuth2 support provides the capability for 3rd-party applications such as Roundcube to authenticate with DMS (dovecot) by using a token obtained from an OAuth2 provider, instead of passing passwords around.
 
-## Example (Authentik & Roundcube)
+## Example (Authentik with Roundcube)
 
-This example assumes you have:
+This example assumes you have already set up:
 
-- A working DMS server set up
+- A working DMS server
-- An Authentik server set up ([documentation](https://goauthentik.io/docs/installation/))
+- An Authentik server ([documentation](https://goauthentik.io/docs/installation/))
-- A Roundcube server set up (either [docker](https://hub.docker.com/r/roundcube/roundcubemail/) or [bare metal](https://github.com/roundcube/roundcubemail/wiki/Installation))
+- A Roundcube server (either [docker](https://hub.docker.com/r/roundcube/roundcubemail/) or [bare metal](https://github.com/roundcube/roundcubemail/wiki/Installation))
 
 !!! example "Setup Instructions"
 

docs/mkdocs.yml

@@ -144,8 +144,8 @@ nav:
         - 'File Based': config/account-management/provisioner/file.md
         - 'LDAP Service': config/account-management/provisioner/ldap.md
       - 'Supplementary':
-        - 'OAuth2 Authentication': config/account-management/supplementary/oauth2.md
         - 'Dovecot Master Accounts': config/account-management/supplementary/master-accounts.md
+        - 'OAuth2 Authentication': config/account-management/supplementary/oauth2.md
     - 'Best Practices':
       - 'Auto-discovery': config/best-practices/autodiscover.md
       - 'DKIM, DMARC & SPF': config/best-practices/dkim_dmarc_spf.md