README.md and Documentation Update (#2389)

* follow up on #2383

Fixes a documentation error by which a list would not be rendered
correctly. This has been taken care of.

* update the `README.md`

I felt the need to update the README for several reasons:

1. LDAP issues that the core maintainers team cannot really resolve
2. Cleaning up the somewhat messy structure near the end

The first point goes without explanantion. The second points includes:

2.1. The tagging convention is now easier to read and understand
2.2. Some bullut points or notes have been inlined to "stick" more to
     the content that it actually belongs to
2.3. The note about the "old" `setup.sh` for DMS `10.1.0` has been
     removed as it is obsolete now. We encourage users to upgrade to
     `10.4.0` anyways.
2.4. The markdown code highlighting is now using `CONSOLE` instead of
     `BASH` because `CONSOLE` is more appropriate.
2.5. Capitalized headings
2.6. Updated the section about `./setup.sh help` to be in one place now
     instead of two
2.7. DKIM key generation does now not interfere with user account
     creation.

* adjusted content to PR suggestions

README.md

@@ -38,7 +38,7 @@ If you have issues, read the full `README` **and** the [documentation][documenta
 - [LetsEncrypt](https://letsencrypt.org/) and self-signed certificates
 - [Setup script](https://docker-mailserver.github.io/docker-mailserver/edge/config/setup.sh) to easily configure and maintain your mail-server
 - Basic [Sieve support](https://docker-mailserver.github.io/docker-mailserver/edge/config/advanced/mail-sieve) using dovecot
-- SASLauthd with LDAP auth
+- SASLauthd with LDAP auth (please see the note [down below](#ldap-setup))
 - Persistent data and state
 - [CI/CD](https://github.com/docker-mailserver/docker-mailserver/actions)
 - [Extension Delimiters](http://www.postfix.org/postconf.5.html#recipient_delimiter) (`you+extension@example.com` go to `you@example.com`)
@@ -55,8 +55,7 @@ If you have issues, read the full `README` **and** the [documentation][documenta
 
 - 1 vCore
 - 512MB RAM
-
+- You'll need to deactivate some services like ClamAV to be able to run on a host with 512MB of RAM. Even with 1G RAM you may run into problems without swap, see [FAQ](https://docker-mailserver.github.io/docker-mailserver/edge/faq/#what-system-requirements-are-required-to-run-docker-mailserver-effectively).
-**Note:** You'll need to deactivate some services like ClamAV to be able to run on a host with 512MB of RAM. Even with 1G RAM you may run into problems without swap, see [FAQ](https://docker-mailserver.github.io/docker-mailserver/edge/faq/#what-system-requirements-are-required-to-run-docker-mailserver-effectively).
 
 ## Usage
 
@@ -64,39 +63,29 @@ If you have issues, read the full `README` **and** the [documentation][documenta
 
 [CI/CD](https://github.com/docker-mailserver/docker-mailserver/actions) will automatically build, test and push new images to container registries. Currently, the following registries are supported:
 
-- [DockerHub](https://hub.docker.com/r/mailserver/docker-mailserver)
+1. [DockerHub](https://hub.docker.com/r/mailserver/docker-mailserver)
-- [GitHub Container Registry](https://github.com/orgs/docker-mailserver/packages?repo_name=docker-mailserver)
+2. [GitHub Container Registry](https://github.com/orgs/docker-mailserver/packages?repo_name=docker-mailserver)
 
 All workflows are using the tagging convention listed below. It is subsequently applied to all images.
 
-| Event        | Ref                   | Image Tags                    |
+| Event              | Image Tags                    |
-|--------------|-----------------------|-------------------------------|
+|--------------------|-------------------------------|
-| `push`       | `refs/heads/master`   | `edge`                        |
+| `push` on `master` | `edge`                        |
-| `push tag`   | `refs/tags/[v]1.2.3`  | `1.2.3`, `1.2`, `1`, `latest` |
+| `push tag`         | `1.2.3`, `1.2`, `1`, `latest` |
 
-### Get the tools
+### Get the Tools
 
-Since Docker Mailserver `v10.2.0`, `setup.sh` functionality is included within the Docker image. The external convenience script is no longer required if you prefer using `docker exec <CONTAINER NAME> setup <COMMAND>` instead.
+Since Docker Mailserver `v10.2.0`, **`setup.sh` functionality is included within the container image**. The external convenience script is no longer required if you prefer using `docker exec <CONTAINER NAME> setup <COMMAND>` instead. **If you're new to `docker-mailserver`**, it is recommended to use the script `setup.sh` for convenience.
-
-**Note:** If you're using Docker or Docker Compose and are new to `docker-mailserver`, it is recommended to use the script `setup.sh` for convenience.
 
 ``` BASH
 DMS_GITHUB_URL='https://raw.githubusercontent.com/docker-mailserver/docker-mailserver/master'
 wget "${DMS_GITHUB_URL}/docker-compose.yml"
 wget "${DMS_GITHUB_URL}/mailserver.env"
 wget "${DMS_GITHUB_URL}/setup.sh"
-
 chmod a+x ./setup.sh
-./setup.sh help
 ```
 
-If no `docker-mailserver` container is running, any `./setup.sh` command will check online for the `:latest` image tag (the current stable release), performing a `pull` if necessary followed by running the command in a temporary container.
+### Create a docker-compose Environment
-
-#### `setup.sh` for `docker-mailserver` version `v10.1.x` and below
-
-If you're using `docker-mailserver` version `v10.1.x` or below, you will need to get `setup.sh` with a specific version. Substitute `<VERSION>` with the `docker-mailserver` release version you're using: `wget https://raw.githubusercontent.com/docker-mailserver/docker-mailserver/<VERSION>/setup.sh`.
-
-### Create a docker-compose environment
 
 1. [Install the latest docker-compose](https://docs.docker.com/compose/install/)
 2. Edit `docker-compose.yml` to your liking
@@ -117,6 +106,25 @@ You are able to get a full overview of how the configuration works by either run
 1. `./setup.sh help` which includes the options of `setup.sh`.
 2. `docker run --rm docker.io/mailserver/docker-mailserver:latest setup help` which provides you with all the information on configuration provided "inside" the container itself.
 
+If no `docker-mailserver` container is running, any `./setup.sh` command will check online for the `:latest` image tag (the current _stable_ release), performing a `docker pull ...` if necessary followed by running the command in a temporary container.
+
+``` CONSOLE
+$ ./setup.sh help
+Image 'docker.io/mailserver/docker-mailserver:latest' not found. Pulling ...
+SETUP(1)
+
+NAME
+    setup - 'docker-mailserver' Administration & Configuration script
+...
+
+$ docker run --rm docker.io/mailserver/docker-mailserver:latest setup help
+SETUP(1)
+
+NAME
+    setup - 'docker-mailserver' Administration & Configuration script
+...
+```
+
 #### Starting for the first time
 
 On first start, you will likely see an error stating that there are no mail accounts and the container will exit. You must now do one of two things:
@@ -135,21 +143,30 @@ docker-compose up -d mailserver
 
 # and configure aliases, DKIM and more
 ./setup.sh [-Z] alias add postmaster@<domain> <user@domain>
+```
+
+### Miscellaneous
+
+#### DNS - DKIM
+
+You can (and you should) generate DKIM keys by running
+
+``` BASH
 ./setup.sh [-Z] config dkim
 ```
 
+If you want to see detailed usage information, run
+
+``` BASH
+./setup.sh config dkim help
+```
+
 In case you're using LDAP, the setup looks a bit different as you do not add user accounts directly. Postfix doesn't know your domain(s) and you need to provide it when configuring DKIM:
 
 ``` BASH
 ./setup.sh config dkim domain '<domain.tld>[,<domain2.tld>]'
 ```
 
-If you want to see detailed usage information, run `./setup.sh config dkim help`.
-
-### Miscellaneous
-
-#### DNS - DKIM
-
 When keys are generated, you can configure your DNS server by just pasting the content of `config/opendkim/keys/domain.tld/mail.txt` to [set up DKIM](https://mxtoolbox.com/dmarc/dkim/setup/how-to-setup-dkim). See the [documentation](https://docker-mailserver.github.io/docker-mailserver/edge/config/best-practices/dkim/) for more details.
 
 #### Custom User Changes & Patches
@@ -158,7 +175,7 @@ If you'd like to change, patch or alter files or behavior of `docker-mailserver`
 
 #### Updating `docker-mailserver`
 
-Make sure to read the [CHANGELOG](https://github.com/docker-mailserver/docker-mailserver/blob/master/CHANGELOG.md) before updating to new versions, to be prepared for possible breaking changes.
+**Make sure to read the [CHANGELOG](https://github.com/docker-mailserver/docker-mailserver/blob/master/CHANGELOG.md)** before updating to new versions, to be prepared for possible breaking changes.
 
 ``` BASH
 docker-compose pull
@@ -243,7 +260,9 @@ services:
     restart: always
 ```
 
-#### LDAP setup
+### LDAP Setup
+
+**Note** There are currently no LDAP maintainers. If you encounter issues, please raise them in the issue tracker, but be aware that the core maintainers team will most likely not be able to help you. **We would appreciate and we encourage everyone to actively participate in maintaining LDAP-related code by becoming a maintainer!**
 
 ``` YAML
 version: '3.8'

docs/content/config/security/ssl.md

@@ -102,8 +102,7 @@ You don't have to do anything else. Enjoy!
 
 #### Example using Docker for _Let's Encrypt_ { data-toc-label='Certbot with Docker' }
 
-- Certbot provisions certificates to `/etc/letsencrypt`. Add a volume to store these, so that they can later be accessed by `docker-mailserver` container.
+Certbot provisions certificates to `/etc/letsencrypt`. Add a volume to store these, so that they can later be accessed by `docker-mailserver` container. You may also want to persist Certbot [logs][certbot::log-rotation], just in case you need to troubleshoot.
-- You may also want to persist Certbot [logs][certbot::log-rotation], just in case you need to troubleshoot.
 
 1. Getting a certificate is this simple! (_Referencing: [Certbot docker instructions][certbot::docker] and [`certonly --standalone` mode][certbot::standalone]_):
 
@@ -119,7 +118,7 @@ You don't have to do anything else. Enjoy!
 
 2. Add a volume for `docker-mailserver` that maps the _local `certbot/certs/` folder_ to the container path `/etc/letsencrypt/`.
 
-!!! example
+    !!! example
 
         Add these additions to the `mailserver` service in your [`docker-compose.yml`][github-file-compose]: