diff --git a/docs/source/markdown/options/add-host.md b/docs/source/markdown/options/add-host.md
index 649bccf7b3..4b4ad1e7ec 100644
--- a/docs/source/markdown/options/add-host.md
+++ b/docs/source/markdown/options/add-host.md
@@ -2,10 +2,28 @@
 ####>   podman build, create, farm build, pod create, run
 ####> If file is edited, make sure the changes
 ####> are applicable to all of those.
-#### **--add-host**=*host:ip*
+#### **--add-host**=*hostname[;hostname[;...]]*:*ip*
 
-Add a custom host-to-IP mapping (host:ip)
-Multiple hostnames for the same IP can be separated by semicolons.
+Add a custom host-to-IP mapping to the <<container|pod>>'s `/etc/hosts` file.
 
-Add a line to /etc/hosts. The format is hostname:ip or hostname1;hostname2;hostname3:ip if you want to map multiple hostnames to the same ip without duplicating the --add-host parameter. The **--add-host**
-option can be set multiple times. Conflicts with the **--no-hosts** option.
+The option takes one or multiple semicolon-separated hostnames to be mapped to
+a single IPv4 or IPv6 address, separated by a colon. It can also be used to
+overwrite the IP addresses of hostnames Podman adds to `/etc/hosts` by default
+(also see the **--name** and **--hostname** options). This option can be
+specified multiple times to add additional mappings to `/etc/hosts`. It
+conflicts with the **--no-hosts** option.
+
+Instead of an IP address, the special flag *host-gateway* can be given. This
+resolves to an IP address the container can use to connect to the host. The
+IP address chosen depends on your network setup, thus there's no guarantee that
+Podman can determine the *host-gateway* address automatically, which will then
+cause Podman to fail with an error message. You can overwrite this IP address
+using the *host_containers_internal_ip* option in *containers.conf*.
+
+The *host-gateway* address is also used by Podman to automatically add the
+`host.containers.internal` and `host.docker.internal` hostnames to `/etc/hosts`.
+You can prevent that by either giving the **--no-hosts** option, or by setting
+*host_containers_internal_ip="none"* in *containers.conf*. If no *host-gateway*
+address was configured manually and Podman fails to determine the IP address
+automatically, Podman will silently skip adding these internal hostnames to
+`/etc/hosts`.