diff --git a/docs/config.md b/docs/config.md
index 273188998..b021cae7e 100644
--- a/docs/config.md
+++ b/docs/config.md
@@ -100,10 +100,6 @@ directories to diff are passed as the first and second argument respectively.
 
 For example:
 
-    ui.diff-editor = "vimdiff"
-
-When kdiff3 is set via:
-
     ui.diff-editor = "kdiff3"
 
 Custom arguments can be added, and will be inserted before the paths
@@ -112,6 +108,14 @@ to diff:
     # merge-tools.kdiff3.program = "kdiff3"      # Defaults to the name of the tool if not specified
     merge-tools.kdiff3.edit-args = ["--merge", "--cs", "CreateBakFiles=0"]
 
+### Using Vim as a diff editor
+
+Using `ui.diff-editor = "vimdiff"` is possible but not recommended.
+For a better experience, you can follow these [instructions] to
+configure the [`DirDiff` Vim plugin].
+
+[instructions]: https://gist.github.com/ilyagr/5d6339fb7dac5e7ab06fe1561ec62d45
+[`DirDiff` Vim plugin]: https://github.com/will133/vim-dirdiff
 
 ## 3-way merge tools for conflict resolution
 
diff --git a/src/merge-tools.toml b/src/merge-tools.toml
index b41b02840..d8229ef16 100644
--- a/src/merge-tools.toml
+++ b/src/merge-tools.toml
@@ -8,6 +8,12 @@ merge-args = ["$left", "$base", "$right", "-o", "$output", "--auto-merge"]
 
 [merge-tools.vimdiff]
 program = "vim"
+# `-d` enables diff mode. `-f` makes vim run in foreground even if it starts a GUI.
+# The other options make sure that only the output file can be modified.
 merge-args = ["-f", "-d", "$output", "-M", "$left", "$base", "$right",
               "-c", "wincmd J", "-c", "set modifiable", "-c", "set write"]
 merge-tool-edits-conflict-markers = true
+# Using vimdiff as a diff editor is not recommended. For instructions on configuring
+# the DirDiff Vim plugin for a better experience, see
+# https://gist.github.com/ilyagr/5d6339fb7dac5e7ab06fe1561ec62d45
+edit-args = ["-f", "-d"]