diff --git a/doc/cabal-commands.rst b/doc/cabal-commands.rst
index 7671e41cdf96e3e017ba88017d7ddd116878298c..2773eae8217597ae1601144d9383e031de9fded7 100644
--- a/doc/cabal-commands.rst
+++ b/doc/cabal-commands.rst
@@ -845,6 +845,8 @@ The configuration information for the script is cached under the cabal directory
 and can be pre-built with ``cabal build path/to/script``.
 See ``cabal run`` for more information on scripts.
 
+.. _cabal run:
+
 cabal run
 ^^^^^^^^^
 
diff --git a/doc/getting-started.rst b/doc/getting-started.rst
index f1a64d6b0c02f8e6959cd6d3022822df0ca88eee..416a5dd77ae1cb6552d441172e07fb9edb72065d 100644
--- a/doc/getting-started.rst
+++ b/doc/getting-started.rst
@@ -166,6 +166,44 @@ Now you can build and re-run your code to see the new output:
         /    /  /    /   \    \
        /____/  /____/     \____\
 
+Run a single-file Haskell script
+--------------------------------
+
+Cabal also enables us to run single-file Haskell scripts
+without creating a project directory or ``.cabal`` file.
+The cabal directives are placed in the file within a comment.
+
+.. code-block:: haskell
+
+    #!/usr/bin/env cabal
+    {- cabal:
+    build-depends: base, split
+    -}
+
+    import Data.List.Split (chunksOf)
+
+    main :: IO ()
+    main = getLine >>= print . chunksOf 3
+
+This can be run using ``cabal run myscript``.
+On Unix-like systems this can be run directly with execute permission.
+
+.. code-block:: console
+
+    $ cabal run myscript
+
+    $ chmod +x myscript
+    $ ./myscript
+
+Project metadata can also be included:
+
+.. code-block:: haskell
+
+    {- project:
+    with-compiler: ghc-8.10.7
+    -}
+
+See more in the documentation for :ref:`cabal run`.
 
 What Next?
 ----------