diff --git a/docs/xdebug.md b/docs/xdebug.md
index 5dd9522..1a6ea89 100644
--- a/docs/xdebug.md
+++ b/docs/xdebug.md
@@ -1,7 +1,8 @@
 # Installing Xdebug
 
-The default Docker stack is shipped without a Xdebug stage.
-It's easy though to add [Xdebug](https://xdebug.org/) to your project, for development purposes such as debugging tests or API requests remotely.
+The default Docker stack is shipped without [Xdebug](https://xdebug.org/),
+a popular debugger and profiler for PHP.
+It's easy, though, to add it to your project.
 
 ## Add a Debug Stage to the Dockerfile
 
@@ -12,7 +13,7 @@ it's recommended to add a custom stage to the end of the `Dockerfile`.
 # Dockerfile
 FROM symfony_php AS symfony_php_debug
 
-ARG XDEBUG_VERSION=3.0.4
+ARG XDEBUG_VERSION=3.1.2
 RUN set -eux; \
 	apk add --no-cache --virtual .build-deps $PHPIZE_DEPS; \
 	pecl install xdebug-$XDEBUG_VERSION; \
@@ -25,7 +26,7 @@ RUN set -eux; \
 Using an [override](https://docs.docker.com/compose/reference/overview/#specifying-multiple-compose-files) file named `docker-compose.debug.yml` ensures that the production
 configuration remains untouched.
 
-As example, an override could look like this:
+As an example, an override could look like this:
 
 ```yaml
 # docker-compose.debug.yml
@@ -47,9 +48,12 @@ services:
       # This should correspond to the server declared in PHPStorm `Preferences | Languages & Frameworks | PHP | Servers`
       # Then PHPStorm will use the corresponding path mappings
       PHP_IDE_CONFIG: serverName=symfony
+    extra_hosts:
+      # Ensure that host.docker.internal is correctly defined on Linux
+      - host.docker.internal:host-gateway
 ```
 
-Build your image with your fresh new xdebug configuration:
+Build your image with your fresh new XDebug configuration:
 
 ```console
 docker-compose -f docker-compose.yml -f docker-compose.debug.yml build
@@ -65,29 +69,29 @@ docker-compose -f docker-compose.yml -f docker-compose.debug.yml up -d
 
 You can use the **Xdebug extension** for [Chrome](https://chrome.google.com/webstore/detail/xdebug-helper/eadndfjplgieldjbigjakmdgkmoaaaoc) or [Firefox](https://addons.mozilla.org/fr/firefox/addon/xdebug-helper-for-firefox/) if you want to debug on the browser (don't forget to configure it).
 
-If you don't want to use it, just add on your request this query param: `XDEBUG_SESSION=PHPSTORM`.
+If you don't want to use it, add on your request this query param: `XDEBUG_SESSION=PHPSTORM`.
 
-On PHPStorm, you just have to click on  the button `Start Listening for PHP Debug Connections` on the `Run` menu.
+On PHPStorm, click on `Start Listening for PHP Debug Connections` in the `Run` menu.
 
 Otherwise, you can create a [PHP Remote Debug](https://www.jetbrains.com/help/phpstorm/creating-a-php-debug-server-configuration.html) configuration with the following parameters:
 
 * Server:
-  * Name: **symfony** (must be the same as defined in *PHP_IDE_CONFIG*)
-  * Host: **https://localhost** (or the one defined with *SERVER_NAME*)
-  * Port: **443**
-  * Debugger: **Xdebug**
-  * Absolute path on the server: **/srv/app**
-* IDE key: **PHPSTORM**
+  * Name: `symfony` (must be the same as defined in `PHP_IDE_CONFIG`)
+  * Host: `https://localhost` (or the one defined with `SERVER_NAME`)
+  * Port: `443`
+  * Debugger: `Xdebug`
+  * Absolute path on the server: `/srv/app`
+* IDE key: `PHPSTORM`
 
 You can now use the debugger.
 
 ## Troubleshooting
 
-Inspect the installation with the following command. The requested Xdebug version should be displayed in the output.
+Inspect the installation with the following command. The Xdebug version should be displayed.
 
 ```console
 $ docker-compose exec php php --version
 
 PHP ...
-    with Xdebug v3.0.4 ...
+    with Xdebug v3.1.2 ...
 ```