diff --git a/docs/docker/l3d/drupal.md b/docs/docker/l3d/drupal.md
index 5a4cd076481d5c52ab1adc2db88748b1df479f9a..fefb6c2fbbda53eec59f63fa6dbd4e448200cde0 100644
--- a/docs/docker/l3d/drupal.md
+++ b/docs/docker/l3d/drupal.md
@@ -5,6 +5,8 @@ tags:
 ---
 # L3D and Drupal Projects
 
+## Introduction and overview
+
 We do provide a couple of project templates for Drupal projects out of the box:
 
 - [Drupal 8](/composer/project/d8)
@@ -175,3 +177,33 @@ DOCKER4DRUPAL_TRAEFIK_KEY=privkey.pem
 To update your Traefik configuration and restart the service, go to one of your
 projects in L3D and call `ahoy traefik rewrite` to get everything setup once and
 forever.
+
+## Using XDebug
+
+Debugging PHP can be a game changer in Drupal development. In the context of L3D
+in combination with the composer plugin [Docker4Drupal](/composer/plugin/d4d)
+this is provided out of the box and configured very easily. We describe the
+steps for PhpStorm, but other IDEs should be very similar.
+
+As XDebug comes with a performance hit, it is turned off by default. When you
+need it, simply call `ahoy debug on` in you L3D container of the project you
+want to debug and the scripts will reconfigure the PHP container and refresh
+it with a few seconds. When you've finished debugging, you may want to turn it
+off again with `ahoy debug off`.
+
+XDebug version 3 connects to port 9003 of your IDE and PhpStorm is preconfigured
+by default to list on that port.
+
+You can then just enable debugging in PhpStorm and wait for the first request
+which will prompt you to configure the details. Or you configure actively the
+debug configuration:
+
+![Screenshot](/files/screenshots/Screenshot from 2021-01-25 18-59-52.png)
+
+The name and the server name should both be called `Docker`. And the mapping
+needs to be configured from your project root directory on your host to the
+path `/var/www/html` in the container.
+
+With this setup, you can debug both web requests coming from the browser and
+CLI commands for PHP which is executed inside the PHP container like e.g.
+drush - all with the same setup.
diff --git a/docs/files/screenshots/Screenshot from 2021-01-25 18-59-52.png b/docs/files/screenshots/Screenshot from 2021-01-25 18-59-52.png
new file mode 100644
index 0000000000000000000000000000000000000000..1dfdcf5168c2105e166cb2f1d2f9f1895b1b0593
--- /dev/null
+++ b/docs/files/screenshots/Screenshot from 2021-01-25 18-59-52.png	
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:15bf7605ea1241b40b71622fbe278fdd313c5ea09e0b271ddd00673a6bb3b2b6
+size 48764