diff --git a/pages/common/pio-debug.md b/pages/common/pio-debug.md
new file mode 100644
index 0000000000..745037df60
--- /dev/null
+++ b/pages/common/pio-debug.md
@@ -0,0 +1,24 @@
+# pio debug
+
+> Debug PlatformIO projects.
+> More information: <https://docs.platformio.org/en/latest/core/userguide/cmd_debug.html>.
+
+- Debug the PlatformIO project in the current directory:
+
+`pio debug`
+
+- Debug a specific PlatformIO project:
+
+`pio debug --project-dir {{path/to/platformio_project}}`
+
+- Debug a specific environment:
+
+`pio debug --environment {{environment}}`
+
+- Debug a PlatformIO project using a specific configuration file:
+
+`pio debug --project-conf {{path/to/platformio.ini}}`
+
+- Debug a PlatformIO project using the `gdb` debugger:
+
+`pio debug --interface={{gdb}} {{gdb_options}}`
diff --git a/pages/common/piodebuggdb.md b/pages/common/piodebuggdb.md
new file mode 100644
index 0000000000..7735048012
--- /dev/null
+++ b/pages/common/piodebuggdb.md
@@ -0,0 +1,7 @@
+# piodebuggdb
+
+> This command is an alias of `pio debug --interface=gdb`.
+
+- View documentation for the original command:
+
+`tldr pio debug`