diff --git a/src/nix/repl.cc b/src/nix/repl.cc
index a992d8732..bce8d31dc 100644
--- a/src/nix/repl.cc
+++ b/src/nix/repl.cc
@@ -405,6 +405,7 @@ bool NixRepl::processLine(string line)
     }
 
     if (command == ":?" || command == ":help") {
+        // FIXME: convert to Markdown, include in the 'nix repl' manpage.
         std::cout
              << "The following commands are available:\n"
              << "\n"
@@ -801,14 +802,11 @@ struct CmdRepl : StoreCommand, MixEvalArgs
         return "start an interactive environment for evaluating Nix expressions";
     }
 
-    Examples examples() override
+    std::string doc() override
     {
-        return {
-          Example{
-            "Display all special commands within the REPL:",
-            "nix repl\nnix-repl> :?"
-          }
-        };
+        return
+          #include "repl.md"
+          ;
     }
 
     void run(ref<Store> store) override
diff --git a/src/nix/repl.md b/src/nix/repl.md
new file mode 100644
index 000000000..bba60f871
--- /dev/null
+++ b/src/nix/repl.md
@@ -0,0 +1,57 @@
+R""(
+
+# Examples
+
+* Display all special commands within the REPL:
+
+  ```console
+  # nix repl
+  nix-repl> :?
+  ```
+
+* Evaluate some simple Nix expressions:
+
+  ```console
+  # nix repl
+
+  nix-repl> 1 + 2
+  3
+
+  nix-repl> map (x: x * 2) [1 2 3]
+  [ 2 4 6 ]
+  ```
+
+* Interact with Nixpkgs in the REPL:
+
+  ```console
+  # nix repl '<nixpkgs>'
+
+  Loading '<nixpkgs>'...
+  Added 12428 variables.
+
+  nix-repl> emacs.name
+  "emacs-27.1"
+
+  nix-repl> emacs.drvPath
+  "/nix/store/lp0sjrhgg03y2n0l10n70rg0k7hhyz0l-emacs-27.1.drv"
+
+  nix-repl> drv = runCommand "hello" { buildInputs = [ hello ]; } "hello > $out"
+
+  nix-repl> :b x
+  this derivation produced the following outputs:
+    out -> /nix/store/0njwbgwmkwls0w5dv9mpc1pq5fj39q0l-hello
+
+  nix-repl> builtins.readFile drv
+  "Hello, world!\n"
+  ```
+
+# Description
+
+This command provides an interactive environment for evaluating Nix
+expressions. (REPL stands for 'read–eval–print loop'.)
+
+On startup, it loads the Nix expressions named *files* and adds them
+into the lexical scope. You can load addition files using the `:l
+<filename>` command, or reload all files using `:r`.
+
+)""