diff --git a/src/libexpr/primops.cc b/src/libexpr/primops.cc
index 1d04aeb2e..1ff2d5f0b 100644
--- a/src/libexpr/primops.cc
+++ b/src/libexpr/primops.cc
@@ -258,62 +258,71 @@ static RegisterPrimOp primop_import({
     .args = {"path"},
     // TODO turn "normal path values" into link below
     .doc = R"(
-      Load, parse and return the Nix expression in the file *path*.
-
-      The *path* argument must meet the same criteria as an [interpolated expression](@docroot@/language/string-interpolation.md#interpolated-expression).
-
-      If *path* is a directory, the file `default.nix` in that directory
-      is loaded.
-
-      Evaluation aborts if the file doesn’t exist or contains
-      an incorrect Nix expression. `import` implements Nix’s module
-      system: you can put any Nix expression (such as a set or a
-      function) in a separate file, and use it from Nix expressions in
-      other files.
+      Load, parse, and return the Nix expression in the file *path*.
 
       > **Note**
       >
       > Unlike some languages, `import` is a regular function in Nix.
-      > Paths using the angle bracket syntax (e.g., `import` *\<foo\>*)
-      > are normal [path values](@docroot@/language/values.md#type-path).
 
-      A Nix expression loaded by `import` must not contain any *free
-      variables* (identifiers that are not defined in the Nix expression
-      itself and are not built-in). Therefore, it cannot refer to
-      variables that are in scope at the call site. For instance, if you
-      have a calling expression
+      The *path* argument must meet the same criteria as an [interpolated expression](@docroot@/language/string-interpolation.md#interpolated-expression).
 
-      ```nix
-      rec {
-        x = 123;
-        y = import ./foo.nix;
-      }
-      ```
+      If *path* is a directory, the file `default.nix` in that directory is used if it exists.
 
-      then the following `foo.nix` will give an error:
+      > **Example**
+      >
+      > ```console
+      > $ echo 123 > default.nix
+      > ```
+      >
+      > Import `default.nix` from the current directory.
+      >
+      > ```nix
+      > import ./.
+      > ```
+      >
+      >     123
 
-      ```nix
-      x + 456
-      ```
+      Evaluation aborts if the file doesn’t exist or contains an invalid Nix expression.
 
-      since `x` is not in scope in `foo.nix`. If you want `x` to be
-      available in `foo.nix`, you should pass it as a function argument:
+      A Nix expression loaded by `import` must not contain any *free variables*, that is, identifiers that are not defined in the Nix expression itself and are not built-in.
+      Therefore, it cannot refer to variables that are in scope at the call site.
 
-      ```nix
-      rec {
-        x = 123;
-        y = import ./foo.nix x;
-      }
-      ```
-
-      and
-
-      ```nix
-      x: x + 456
-      ```
-
-      (The function argument doesn’t have to be called `x` in `foo.nix`;
-      any name would work.)
+      > **Example**
+      >
+      > If you have a calling expression
+      >
+      > ```nix
+      > rec {
+      >   x = 123;
+      >   y = import ./foo.nix;
+      > }
+      > ```
+      >
+      >  then the following `foo.nix` will give an error:
+      >
+      >  ```nix
+      >  # foo.nix
+      >  x + 456
+      >  ```
+      >
+      >  since `x` is not in scope in `foo.nix`.
+      > If you want `x` to be available in `foo.nix`, pass it as a function argument:
+      >
+      >  ```nix
+      >  rec {
+      >    x = 123;
+      >    y = import ./foo.nix x;
+      >  }
+      >  ```
+      >
+      >  and
+      >
+      >  ```nix
+      >  # foo.nix
+      >  x: x + 456
+      >  ```
+      >
+      >  The function argument doesn’t have to be called `x` in `foo.nix`; any name would work.
     )",
     .fun = [](EvalState & state, const PosIdx pos, Value * * args, Value & v)
     {