diff --git a/doc/Makefile.am b/doc/Makefile.am
index 28933384..5c22d776 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -11,12 +11,16 @@ header_files = \
$(srcdir)/clickpad-softbuttons.dox \
$(srcdir)/device-configuration-via-udev.dox \
$(srcdir)/normalization-of-relative-motion.dox \
+ $(srcdir)/scrolling.dox \
$(srcdir)/seats.dox \
$(srcdir)/t440-support.dox
diagram_files = \
$(srcdir)/dot/seats-sketch.gv \
- $(srcdir)/dot/seats-sketch-libinput.gv
+ $(srcdir)/dot/seats-sketch-libinput.gv \
+ $(srcdir)/svg/button-scrolling.svg \
+ $(srcdir)/svg/edge-scrolling.svg \
+ $(srcdir)/svg/twofinger-scrolling.svg
html/index.html: libinput.doxygen $(header_files) $(diagram_files)
$(AM_V_GEN)(cat $<; \
diff --git a/doc/libinput.doxygen.in b/doc/libinput.doxygen.in
index 4d2a0abf..8fb045e8 100644
--- a/doc/libinput.doxygen.in
+++ b/doc/libinput.doxygen.in
@@ -842,7 +842,7 @@ EXAMPLE_RECURSIVE = NO
# that contain images that are to be included in the documentation (see the
# \image command).
-IMAGE_PATH =
+IMAGE_PATH = svg
# The INPUT_FILTER tag can be used to specify a program that doxygen should
# invoke to filter for each input file. Doxygen will invoke the filter program
diff --git a/doc/scrolling.dox b/doc/scrolling.dox
new file mode 100644
index 00000000..3ded909d
--- /dev/null
+++ b/doc/scrolling.dox
@@ -0,0 +1,50 @@
+/**
+@page scrolling Scrolling
+
+libinput supports three different types of scrolling behavior.
+
+@section twofinger_scrolling Two-finger scrolling
+
+The default on two-finger capable touchpads (almost all modern touchpads are
+capable of detecting two fingers). Scrolling is triggered by two fingers
+being placed on the surface of the touchpad, then moving those fingers
+vertically or horizontally.
+
+@image html twofinger-scrolling.svg "Vertical and horizontal two-finger scrolling"
+
+For scrolling to trigger, a built-in distance threshold has to be met but once
+engaged any movement will scroll. In other words, to start scrolling a
+sufficiently large movement is required, once scrolling tiny amounts of
+movements will translate into tiny scroll movements.
+
+Scrolling in both directions at once is possible by meeting the required
+distance thresholds to enable each direction separately.
+
+@section edge_scrolling Edge scrolling
+
+On some touchpads, edge scrolling is available, triggered by moving a single
+finger along the right edge (vertical scroll) or bottom edge (horizontal
+scroll).
+
+@image html edge-scrolling.svg "Vertical and horizontal edge scrolling"
+
+Due to the layout of the edges, diagonal scrolling is not possible.
+
+Edge scrolling conflicts with @ref clickpad_softbuttons and is
+not usually available on clickpads.
+
+@section button_scrolling On-Button scrolling
+
+Scrolling when a button is held down is available on selected devices. The
+motion of a device is converted into scrolling motion.
+
+For example, Lenovo devices provide a
+pointing stick that emulates
+scroll events when the trackstick's middle mouse button is held down.
+
+@image html button-scrolling.svg "Button scrolling"
+
+Note that libinput's @ref t440_support enables the use of the middle
+button for button scrolling (even when the touchpad is disabled).
+
+*/
diff --git a/doc/svg/button-scrolling.svg b/doc/svg/button-scrolling.svg
new file mode 100644
index 00000000..476c9c7d
--- /dev/null
+++ b/doc/svg/button-scrolling.svg
@@ -0,0 +1,292 @@
+
+
+
+
diff --git a/doc/svg/edge-scrolling.svg b/doc/svg/edge-scrolling.svg
new file mode 100644
index 00000000..cba72c50
--- /dev/null
+++ b/doc/svg/edge-scrolling.svg
@@ -0,0 +1,126 @@
+
+
+
+
diff --git a/doc/svg/twofinger-scrolling.svg b/doc/svg/twofinger-scrolling.svg
new file mode 100644
index 00000000..e182a7fe
--- /dev/null
+++ b/doc/svg/twofinger-scrolling.svg
@@ -0,0 +1,165 @@
+
+
+
+