diff --git a/doc/_static/css/custom.css b/doc/_static/css/custom.css
new file mode 100644
index 00000000000..3d96c70d1f8
--- /dev/null
+++ b/doc/_static/css/custom.css
@@ -0,0 +1,26 @@
+.rst-content .cabal-cmdline-opts {
+  margin-top: 0.3rem;
+  margin-bottom: 0.5rem;
+}
+
+.rst-content .cabal-cmdline-opts .cabal-cmdline-option {
+  margin-top: 0;
+  margin-bottom: 0.12rem;
+}
+
+.rst-content .cabal-cmdline-opts .cabal-cmdline-option:last-child {
+  margin-bottom: 0;
+}
+
+.rst-content .cabal-cmdline-opts .cabal-cmdline-icon {
+  opacity: 0.65;
+}
+
+.rst-content .cabal-cmdline-opts .cabal-cmdline-option code,
+.rst-content .cabal-cmdline-opts .cabal-cmdline-option code.literal,
+.rst-content .cabal-cmdline-opts .cabal-cmdline-option tt.literal {
+  border: 0;
+  background: transparent;
+  padding: 0;
+  color: inherit;
+}
diff --git a/doc/cabal-commands.rst b/doc/cabal-commands.rst
index eb239a9285a..30e74891d0d 100644
--- a/doc/cabal-commands.rst
+++ b/doc/cabal-commands.rst
@@ -1689,3 +1689,344 @@ cabal report
    Package repository to which the report is to be uploaded.
 
 .. include:: references.inc
+
+Undocumented options
+--------------------
+
+For the most part, these options are the command line versions of :ref:`project
+configuration<cabal-project-file>` field options.
+
+Global configuration options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. option:: --jobs
+
+    See :cfg-field:`jobs` for more information.
+
+.. option:: --keep-going
+
+    See :cfg-field:`keep-going` for more information.
+
+.. option:: --semaphore, --no-semaphore
+
+    See :cfg-field:`semaphore` for more information.
+
+Solver configuration options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. option:: --constraint
+
+    See :cfg-field:`constraints` for more information.
+
+.. option:: --reject-unconstrained-dependencies
+
+    See :cfg-field:`reject-unconstrained-dependencies` for more information.
+
+Package configuration options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. option:: --compiler
+
+    See :cfg-field:`compiler` for more information.
+
+.. option:: --configure-option
+
+    See :cfg-field:`configure-options` for more information.
+
+.. option:: --enable-benchmarks
+
+    See :cfg-field:`benchmarks` for more information.
+
+.. option:: --enable-tests
+
+    See :cfg-field:`tests` for more information.
+
+.. option:: --extra-prog-path
+
+    See :cfg-field:`extra-prog-path` for more information.
+
+.. option:: --flags
+
+    See :cfg-field:`flags` for more information.
+
+.. option:: --run-tests
+
+    See :cfg-field:`run-tests` for more information.
+
+.. option:: --with-hc-pkg
+
+    See :cfg-field:`with-hc-pkg` for more information.
+
+Package object code options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. option:: --enable-debug-info, --disable-debug-info
+
+    See :cfg-field:`debug-info` for more information.
+
+.. option:: --enable-executable-stripping, --disable-executable-stripping
+
+    See :cfg-field:`executable-stripping` for more information.
+
+.. option:: --enable-library-stripping, --disable-library-stripping
+
+    See :cfg-field:`library-stripping` for more information.
+
+.. option:: --enable-optimization, --disable-optimization
+
+    See :cfg-field:`optimization` for more information.
+
+.. option:: --enable-split-objs, --disable-split-objs
+
+    See :cfg-field:`split-objs` for more information.
+
+.. option:: --enable-split-sections, --disable-split-sections
+
+    See :cfg-field:`split-sections` for more information.
+
+Executable options
+^^^^^^^^^^^^^^^^^^
+
+.. option:: --program-prefix
+
+    See :cfg-field:`program-prefix` for more information.
+
+.. option:: --program-suffix
+
+    See :cfg-field:`program-suffix` for more information.
+
+Dynamic linking options
+^^^^^^^^^^^^^^^^^^^^^^^
+
+.. option:: --enable-executable-dynamic, --disable-executable-dynamic
+
+    See :cfg-field:`executable-dynamic` for more information.
+
+.. option:: --enable-library-bytecode, --disable-library-bytecode
+
+    See :cfg-field:`library-bytecode` for more information.
+
+.. option:: --enable-library-for-ghci, --disable-library-for-ghci
+
+    See :cfg-field:`library-for-ghci` for more information.
+
+.. option:: --enable-shared, --disable-shared
+
+    See :cfg-field:`shared` for more information.
+
+.. option:: --relocatable
+
+    See :cfg-field:`relocatable` for more information.
+
+Dynamic linking options
+^^^^^^^^^^^^^^^^^^^^^^^
+
+.. option:: --enable-executable-static, --disable-executable-static
+
+    See :cfg-field:`executable-static` for more information.
+
+.. option:: --enable-static, --disable-static
+
+    See :cfg-field:`static` for more information.
+
+Foreign function interface options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. option:: --extra-include-dirs
+
+    See :cfg-field:`extra-include-dirs` for more information.
+
+.. option:: --extra-lib-dirs
+
+    See :cfg-field:`extra-lib-dirs` for more information.
+
+.. option:: --extra-framework-dirs
+
+    See :cfg-field:`extra-framework-dirs` for more information.
+
+Profiling options
+^^^^^^^^^^^^^^^^^
+
+.. option:: --enable-executable-profiling, --disable-executable-profiling
+
+    See :cfg-field:`executable-profiling` for more information.
+
+.. option:: --enable-library-profiling, --disable-library-profiling
+
+    See :cfg-field:`library-profiling` for more information.
+
+.. option:: --enable-library-vanilla, --disable-library-vanilla
+
+    See :cfg-field:`library-vanilla` for more information.
+
+.. option:: --enable-profiling, --disable-profiling
+
+    See :cfg-field:`profiling` for more information.
+
+.. option:: --library-profiling-detail
+
+    See :cfg-field:`library-profiling-detail` for more information.
+
+.. option:: --profiling-detail
+
+    See :cfg-field:`profiling-detail` for more information.
+
+Coverage options
+^^^^^^^^^^^^^^^^
+
+.. option:: --enable-coverage, --disable-coverage
+
+    See :cfg-field:`coverage` for more information.
+
+.. option:: --enable-library-coverage, --disable-library-coverage
+
+    See :cfg-field:`library-coverage` for more information.
+
+Haddock options
+^^^^^^^^^^^^^^^
+
+.. option:: --doc-index-file
+
+    See :cfg-field:`doc-index-file` for more information.
+
+.. option:: --enable-documentation, --disable-documentation
+
+    See :cfg-field:`documentation` for more information.
+
+.. option:: --haddock-all
+
+    See :cfg-field:`haddock-all` for more information.
+
+.. option:: --haddock-benchmarks
+
+    See :cfg-field:`haddock-benchmarks` for more information.
+
+.. option:: --haddock-contents-location
+
+    See :cfg-field:`haddock-contents-location` for more information.
+
+.. option:: --haddock-css
+
+    See :cfg-field:`haddock-css` for more information.
+
+.. option:: --haddock-executables
+
+    See :cfg-field:`haddock-executables` for more information.
+
+.. option:: --haddock-hoogle
+
+    See :cfg-field:`haddock-hoogle` for more information.
+
+.. option:: --haddock-hscolour-css
+
+    See :cfg-field:`haddock-hscolour-css` for more information.
+
+.. option:: --haddock-html
+
+    See :cfg-field:`haddock-html` for more information.
+
+.. option:: --haddock-html-location
+
+    See :cfg-field:`haddock-html-location` for more information.
+
+.. option:: --haddock-hyperlink-source
+
+    See :cfg-field:`haddock-hyperlink-source` for more information.
+
+.. option:: --haddock-internal
+
+    See :cfg-field:`haddock-internal` for more information.
+
+.. option:: --haddock-output-dir
+
+    See :cfg-field:`haddock-output-dir` for more information.
+
+.. option:: --haddock-quickjump
+
+    See :cfg-field:`haddock-quickjump` for more information.
+
+.. option:: --haddock-resources-dir
+
+    See :cfg-field:`haddock-resources-dir` for more information.
+
+.. option:: --haddock-tests
+
+    See :cfg-field:`haddock-tests` for more information.
+
+.. option:: --haddock-use-unicode
+
+    See :cfg-field:`haddock-use-unicode` for more information.
+
+.. option:: --open
+
+    See :cfg-field:`open` for more information.
+
+Advanced configuration options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. option:: --build-summary
+
+    See :cfg-field:`build-summary` for more information.
+
+.. option:: --http-transport
+
+    See :cfg-field:`http-transport` for more information.
+
+.. option:: --ignore-expiry
+
+    See :cfg-field:`ignore-expiry` for more information.
+
+.. option:: --logs-dir
+
+    See :cfg-field:`logs-dir` for more information.
+
+.. option:: --remote-repo-cache
+
+    See :cfg-field:`remote-repo-cache` for more information.
+
+.. option:: --write-ghc-environment-files
+
+    See :cfg-field:`write-ghc-environment-files` for more information.
+
+Advanced solver options
+^^^^^^^^^^^^^^^^^^^^^^^
+
+.. option:: --allow-boot-library-installs, --no-allow-boot-library-installs
+
+    See :cfg-field:`allow-boot-library-installs` for more information.
+
+.. option:: --cabal-lib-version
+
+    See :cfg-field:`cabal-lib-version` for more information.
+
+.. option:: --count-conflicts, --no-count-conflicts
+
+    See :cfg-field:`count-conflicts` for more information.
+
+.. option:: --fine-grained-conflicts, --no-fine-grained-conflicts
+
+    See :cfg-field:`fine-grained-conflicts` for more information.
+
+.. option:: --max-backjumps
+
+    See :cfg-field:`max-backjumps` for more information.
+
+.. option:: --minimize-conflict-set, --no-minimize-conflict-set
+
+    See :cfg-field:`minimize-conflict-set` for more information.
+
+.. option:: --prefer-oldest, --no-prefer-oldest
+
+    See :cfg-field:`prefer-oldest` for more information.
+
+.. option:: --reorder-goals, --no-reorder-goals
+
+    See :cfg-field:`reorder-goals` for more information.
+
+.. option:: --solver
+
+    See :cfg-field:`solver` for more information.
+
+.. option:: --strong-flags, --no-strong-flags
+
+    See :cfg-field:`strong-flags` for more information.
diff --git a/doc/cabal-project-description-file.rst b/doc/cabal-project-description-file.rst
index 8f7639ee1b8..9197c0ddcf6 100644
--- a/doc/cabal-project-description-file.rst
+++ b/doc/cabal-project-description-file.rst
@@ -331,7 +331,9 @@ package, and thus apply globally:
 
 
 .. cfg-field:: verbose: nat
-               -v[n], --verbose[=n]
+    :cmdline-opts:
+        -v[n]
+        --verbose[=n]
     :synopsis: Build verbosity level.
 
     :default: 1
@@ -343,7 +345,10 @@ package, and thus apply globally:
     form ``-v2`` is also supported.
 
 .. cfg-field:: jobs: nat or $ncpus
-               -j[NUM], --jobs[=NUM], --jobs=$ncpus
+    :cmdline-opts:
+        -j[NUM]
+        --jobs[=NUM]
+        --jobs=$ncpus
     :synopsis: Number of builds running in parallel.
 
     :default: 1
@@ -358,8 +363,9 @@ package, and thus apply globally:
     to ``--jobs=$ncpus``.
 
 .. cfg-field::  semaphore: boolean
-                --semaphore
-                --no-semaphore
+    :cmdline-opts:
+        --semaphore
+        --no-semaphore
     :synopsis: Use GHC's support for semaphore based parallelism.
 
     :default: False
@@ -374,7 +380,8 @@ package, and thus apply globally:
     The command line variant of this field is ``--semaphore``.
 
 .. cfg-field::  keep-going: boolean
-                --keep-going
+    :cmdline-opts:
+        --keep-going
     :synopsis: Try to continue building on failure.
 
     :default: False
@@ -452,7 +459,8 @@ package, and thus apply globally:
     Specifies the name of the directory of the global package store.
 
 .. cfg-field:: package-dbs: package DB stack (comma separated)
-               --package-db=[clear, global, user, PATH]
+    :cmdline-opts:
+        --package-db=[clear,global,user,PATH]
     :synopsis: PackageDB stack manipulation
     :since: 3.7
 
@@ -550,8 +558,12 @@ Solver configuration options
 The following settings control the behavior of the dependency solver:
 
 .. cfg-field:: constraints: CONSTRAINT (comma separated list)
-               -c CONSTRAINT or -cCONSTRAINT, --constraint=CONSTRAINT
-               --constraint="pkg >= 2.0", -c "pkg >= 2.0"
+    :cmdline-opts:
+        -c CONSTRAINT
+        -cCONSTRAINT
+        --constraint=CONSTRAINT
+        --constraint="pkg >= 2.0"
+        -c "pkg >= 2.0"
     :synopsis: Extra dependencies constraints.
 
     Add extra constraints to the version bounds, flag settings,
@@ -587,8 +599,9 @@ The following settings control the behavior of the dependency solver:
     command line option.
 
 .. cfg-field:: preferences: CONSTRAINT (comma separated list)
-               --preference=CONSTRAINT
-               --preference="pkg >= 2.0"
+    :cmdline-opts:
+        --preference=CONSTRAINT
+        --preference="pkg >= 2.0"
     :synopsis: Preferred dependency versions.
 
     Like :cfg-field:`constraints`, but the solver will attempt to satisfy
@@ -613,7 +626,9 @@ The following settings control the behavior of the dependency solver:
     the flag multiple times.
 
 .. cfg-field:: allow-newer: none, all or list of scoped package names (space or comma separated)
-               --allow-newer, --allow-newer=[none,all,[scope:][^]pkg]
+    :cmdline-opts:
+        --allow-newer
+        --allow-newer=[none,all,[scope:][^]pkg]
     :synopsis: Lift dependencies upper bound constraints.
 
     :default: ``none``
@@ -706,7 +721,9 @@ The following settings control the behavior of the dependency solver:
     bare ``--allow-newer`` is equivalent to ``--allow-newer=all``.
 
 .. cfg-field:: allow-older: none, all, list of scoped package names (space or comma separated)
-               --allow-older, --allow-older=[none,all,[scope:][^]pkg]
+    :cmdline-opts:
+        --allow-older
+        --allow-older=[none,all,[scope:][^]pkg]
     :synopsis: Lift dependency lower bound constraints.
     :since: 2.0
 
@@ -817,19 +834,20 @@ The following settings control the behavior of the dependency solver:
 
 
 .. cfg-field:: reject-unconstrained-dependencies: all, none
-               --reject-unconstrained-dependencies=[all|none]
-   :synopsis: Restrict the solver to packages that have constraints on them.
+    :cmdline-opts:
+        --reject-unconstrained-dependencies=[all|none]
+    :synopsis: Restrict the solver to packages that have constraints on them.
 
-   :default: none
-   :since: 2.6
+    :default: none
+    :since: 2.6
 
-   By default, the dependency solver can include any package that it's
-   aware of in a build plan. If you wish to restrict the build plan to
-   a closed set of packages (e.g., from a freeze file), use this flag.
+    By default, the dependency solver can include any package that it's
+    aware of in a build plan. If you wish to restrict the build plan to
+    a closed set of packages (e.g., from a freeze file), use this flag.
 
-   When set to `all`, all non-local packages that aren't goals must be
-   explicitly constrained. When set to `none`, the solver will
-   consider all packages.
+    When set to `all`, all non-local packages that aren't goals must be
+    explicitly constrained. When set to `none`, the solver will
+    consider all packages.
 
 .. _package-configuration-options:
 
@@ -891,8 +909,13 @@ feature was added.
 .. cfg-section:: None
 
 .. cfg-field:: flags: list of +flagname or -flagname (space separated)
-               -f FLAGS or -fFLAGS, --flags=FLAGS
-               --flags="+foo -bar", -ffoo, -f-bar
+    :cmdline-opts:
+        -f FLAGS
+        -fFLAGS
+        --flags=FLAGS
+        --flags="+foo -bar"
+        -ffoo
+        -f-bar
     :synopsis: Enable or disable package flags.
 
     Force all flags specified as ``+flagname`` to be true, and all flags
@@ -921,7 +944,10 @@ feature was added.
     package :cfg-field:`constraints`.
 
 .. cfg-field:: with-compiler: PATH
-               -w PATH or -wPATH, --with-compiler=PATH
+    :cmdline-opts:
+        -w PATH
+        -wPATH
+        --with-compiler=PATH
     :synopsis: Path to compiler executable.
 
     Specify the path to a particular compiler to be used. If not an
@@ -952,7 +978,8 @@ feature was added.
     ``-w ghc-7.8``.
 
 .. cfg-field:: with-hc-pkg: PATH
-               --with-hc-pkg=PATH
+    :cmdline-opts:
+        --with-hc-pkg=PATH
     :synopsis: Path to package tool.
 
     Specify the path to the package tool, e.g., ``ghc-pkg``. This
@@ -965,8 +992,10 @@ feature was added.
     ``--with-hc-pkg=ghc-pkg-7.8``.
 
 .. cfg-field:: optimization: nat
-               -O[n], --enable-optimization[=n]
-               --disable-optimization
+    :cmdline-opts:
+        -O[n]
+        --enable-optimization[=n]
+        --disable-optimization
     :synopsis: Build with optimization.
 
     :default: ``1``
@@ -998,7 +1027,8 @@ feature was added.
     ``--enable-optimization`` and ``--disable-optimization``.
 
 .. cfg-field:: configure-options: OPT (space separated list)
-               --configure-option=OPT
+    :cmdline-opts:
+        --configure-option=OPT
     :synopsis: Options to pass to configure script.
 
     A list of extra arguments to pass to the external ``./configure``
@@ -1010,7 +1040,8 @@ feature was added.
     which can be specified multiple times to pass multiple options.
 
 .. cfg-field:: compiler: ghc, ghcjs, jhc, lhc, or uhc
-               --compiler=compiler
+    :cmdline-opts:
+        --compiler=compiler
     :synopsis: Compiler to build with.
 
     :default: ``ghc``
@@ -1025,8 +1056,9 @@ feature was added.
     per-package basis.
 
 .. cfg-field:: tests: boolean
-               --enable-tests
-               --disable-tests
+    :cmdline-opts:
+        --enable-tests
+        --disable-tests
     :synopsis: Build tests.
 
     :default: ``False``
@@ -1040,8 +1072,9 @@ feature was added.
     ``--disable-tests``.
 
 .. cfg-field:: benchmarks: boolean
-               --enable-benchmarks
-               --disable-benchmarks
+    :cmdline-opts:
+        --enable-benchmarks
+        --disable-benchmarks
     :synopsis: Build benchmarks.
 
     :default: ``False``
@@ -1056,7 +1089,8 @@ feature was added.
 
 .. _cmdoption-extra-prog-path:
 .. cfg-field:: extra-prog-path: PATH (newline or comma separated list)
-               --extra-prog-path=PATH
+    :cmdline-opts:
+        --extra-prog-path=PATH
     :synopsis: Add directories to program search path.
     :since: 1.18
 
@@ -1074,7 +1108,8 @@ feature was added.
     program search path.
 
 .. cfg-field:: run-tests: boolean
-               --run-tests
+    :cmdline-opts:
+        --run-tests
     :synopsis: Run package test suite during installation.
 
     :default: ``False``
@@ -1097,8 +1132,9 @@ Object code options
 ^^^^^^^^^^^^^^^^^^^
 
 .. cfg-field:: debug-info: integer
-               --enable-debug-info[=n]
-               --disable-debug-info
+    :cmdline-opts:
+        --enable-debug-info[=n]
+        --disable-debug-info
     :synopsis: Build with debug info enabled.
     :since: 1.22
 
@@ -1116,8 +1152,9 @@ Object code options
     ``--disable-debug-info``.
 
 .. cfg-field:: split-sections: boolean
-               --enable-split-sections
-               --disable-split-sections
+    :cmdline-opts:
+        --enable-split-sections
+        --disable-split-sections
     :synopsis: Use GHC's split sections feature.
     :since: 2.2
 
@@ -1135,8 +1172,9 @@ Object code options
     ``--disable-split-sections``.
 
 .. cfg-field:: split-objs: boolean
-               --enable-split-objs
-               --disable-split-objs
+    :cmdline-opts:
+        --enable-split-objs
+        --disable-split-objs
     :synopsis: Use GHC's split objects feature.
 
     :default: False
@@ -1154,8 +1192,9 @@ Object code options
     ``--disable-split-objs``.
 
 .. cfg-field:: executable-stripping: boolean
-               --enable-executable-stripping
-               --disable-executable-stripping
+    :cmdline-opts:
+        --enable-executable-stripping
+        --disable-executable-stripping
     :synopsis: Strip installed programs.
 
     :default: True
@@ -1176,8 +1215,9 @@ Object code options
     ``--disable-executable-stripping``.
 
 .. cfg-field:: library-stripping: boolean
-               --enable-library-stripping
-               --disable-library-stripping
+    :cmdline-opts:
+        --enable-library-stripping
+        --disable-library-stripping
     :synopsis: Strip installed libraries.
     :since: 1.20
 
@@ -1195,7 +1235,8 @@ Executable options
 ^^^^^^^^^^^^^^^^^^
 
 .. cfg-field:: program-prefix: PREFIX
-               --program-prefix=PREFIX
+    :cmdline-opts:
+        --program-prefix=PREFIX
     :synopsis: Prepend prefix to program names.
 
     :strike:`Prepend *prefix* to installed program names.` (Currently
@@ -1209,7 +1250,8 @@ Executable options
     The command line variant of this flag is ``--program-prefix=foo-``.
 
 .. cfg-field:: program-suffix: SUFFIX
-               --program-suffix=SUFFIX
+    :cmdline-opts:
+        --program-suffix=SUFFIX
     :synopsis: Append refix to program names.
 
     :strike:`Append *suffix* to installed program names.` (Currently
@@ -1231,8 +1273,9 @@ Dynamic linking options
 ^^^^^^^^^^^^^^^^^^^^^^^
 
 .. cfg-field:: shared: boolean
-               --enable-shared
-               --disable-shared
+    :cmdline-opts:
+        --enable-shared
+        --disable-shared
     :synopsis: Build shared library.
 
     :default: False
@@ -1244,8 +1287,9 @@ Dynamic linking options
     ``--disable-shared``.
 
 .. cfg-field:: executable-dynamic: boolean
-               --enable-executable-dynamic
-               --disable-executable-dynamic
+    :cmdline-opts:
+        --enable-executable-dynamic
+        --disable-executable-dynamic
     :synopsis: Link executables dynamically.
 
     :default: False
@@ -1259,8 +1303,9 @@ Dynamic linking options
     ``--disable-executable-dynamic``.
 
 .. cfg-field:: library-for-ghci: boolean
-               --enable-library-for-ghci
-               --disable-library-for-ghci
+    :cmdline-opts:
+        --enable-library-for-ghci
+        --disable-library-for-ghci
     :synopsis: Build libraries suitable for use with GHCi.
 
     :default: True
@@ -1276,8 +1321,9 @@ Dynamic linking options
     ``--enable-library-for-ghci`` and ``--disable-library-for-ghci``.
 
 .. cfg-field:: library-bytecode: boolean
-               --enable-library-bytecode
-               --disable-library-bytecode
+    :cmdline-opts:
+        --enable-library-bytecode
+        --disable-library-bytecode
     :synopsis: Build bytecode libraries.
 
     :default: False
@@ -1295,7 +1341,8 @@ Dynamic linking options
     ``--enable-library-bytecode`` and ``--disable-library-bytecode``.
 
 .. cfg-field:: relocatable:
-               --relocatable
+    :cmdline-opts:
+        --relocatable
     :synopsis: Build relocatable package.
     :since: 1.22
 
@@ -1310,8 +1357,9 @@ Static linking options
 ^^^^^^^^^^^^^^^^^^^^^^
 
 .. cfg-field:: static: boolean
-               --enable-static
-               --disable-static
+    :cmdline-opts:
+        --enable-static
+        --disable-static
     :synopsis: Build static library.
 
 
@@ -1322,8 +1370,9 @@ Static linking options
     GHC 8.4 and later for other platforms as well.
 
 .. cfg-field:: executable-static: boolean
-               --enable-executable-static
-               --disable-executable-static
+    :cmdline-opts:
+        --enable-executable-static
+        --disable-executable-static
     :synopsis: Build fully static executables.
 
 
@@ -1338,7 +1387,8 @@ Foreign function interface options
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. cfg-field:: extra-include-dirs: directories (comma or newline separated list)
-               --extra-include-dirs=DIR
+    :cmdline-opts:
+        --extra-include-dirs=DIR
     :synopsis: Adds C header search path.
 
     An extra directory to search for C header files. You can use this
@@ -1358,7 +1408,8 @@ Foreign function interface options
     ``--extra-include-dirs=DIR``, which can be specified multiple times.
 
 .. cfg-field:: extra-lib-dirs: directories (comma or newline separated list)
-               --extra-lib-dirs=DIR
+    :cmdline-opts:
+        --extra-lib-dirs=DIR
     :synopsis: Adds library search directory.
 
     An extra directory to search for system libraries files.
@@ -1367,7 +1418,8 @@ Foreign function interface options
     which can be specified multiple times.
 
 .. cfg-field:: extra-framework-dirs: directories (comma or newline separated list)
-               --extra-framework-dirs=DIR
+    :cmdline-opts:
+        --extra-framework-dirs=DIR
     :synopsis: Adds framework search directory (OS X only).
 
     An extra directory to search for frameworks (OS X only).
@@ -1392,8 +1444,9 @@ Profiling options
 ^^^^^^^^^^^^^^^^^
 
 .. cfg-field:: profiling: boolean
-               --enable-profiling
-               --disable-profiling
+    :cmdline-opts:
+        --enable-profiling
+        --disable-profiling
     :synopsis: Enable profiling builds.
     :since: 1.22
 
@@ -1417,7 +1470,8 @@ Profiling options
 .. _profiling-detail:
 
 .. cfg-field:: profiling-detail: level
-               --profiling-detail=level
+    :cmdline-opts:
+        --profiling-detail=level
     :synopsis: Profiling detail level.
     :since: 1.24
 
@@ -1465,7 +1519,8 @@ Profiling options
     ``--profiling-detail=none``.
 
 .. cfg-field:: library-profiling-detail: level
-               --library-profiling-detail=level
+    :cmdline-opts:
+        --library-profiling-detail=level
     :synopsis: Libraries profiling detail level.
     :since: 1.24
 
@@ -1475,8 +1530,9 @@ Profiling options
     ``--library-profiling-detail=none``.
 
 .. cfg-field:: library-vanilla: boolean
-               --enable-library-vanilla
-               --disable-library-vanilla
+    :cmdline-opts:
+        --enable-library-vanilla
+        --disable-library-vanilla
     :synopsis: Build libraries without profiling.
 
     :default: True
@@ -1489,8 +1545,9 @@ Profiling options
     ``--enable-library-vanilla`` and ``--disable-library-vanilla``.
 
 .. cfg-field:: library-profiling: boolean
-               --enable-library-profiling
-               --disable-library-profiling
+    :cmdline-opts:
+        --enable-library-profiling
+        --disable-library-profiling
     :synopsis: Build libraries with profiling enabled.
     :since: 1.22
 
@@ -1503,8 +1560,9 @@ Profiling options
     ``--enable-library-profiling`` and ``--disable-library-profiling``.
 
 .. cfg-field:: executable-profiling: boolean
-               --enable-executable-profiling
-               --disable-executable-profiling
+    :cmdline-opts:
+        --enable-executable-profiling
+        --disable-executable-profiling
     :synopsis: Build executables with profiling enabled.
     :since: 1.22
 
@@ -1521,8 +1579,9 @@ Coverage options
 ^^^^^^^^^^^^^^^^
 
 .. cfg-field:: coverage: boolean
-               --enable-coverage
-               --disable-coverage
+    :cmdline-opts:
+        --enable-coverage
+        --disable-coverage
     :synopsis: Build with coverage enabled.
     :since: 1.22
 
@@ -1536,8 +1595,9 @@ Coverage options
     ``--disable-coverage``.
 
 .. cfg-field:: library-coverage: boolean
-               --enable-library-coverage
-               --disable-library-coverage
+    :cmdline-opts:
+        --enable-library-coverage
+        --disable-library-coverage
     :since: 1.22
     :deprecated:
 
@@ -1552,8 +1612,9 @@ Haddock options
 ^^^^^^^^^^^^^^^
 
 .. cfg-field:: documentation: boolean
-               --enable-documentation
-               --disable-documentation
+    :cmdline-opts:
+        --enable-documentation
+        --disable-documentation
     :synopsis: Enable building of documentation.
 
     :default: False
@@ -1573,7 +1634,8 @@ Haddock options
     These need to be enabled separately if desired.
 
 .. cfg-field:: doc-index-file: templated path
-               --doc-index-file=TEMPLATE
+    :cmdline-opts:
+        --doc-index-file=TEMPLATE
     :synopsis: Path to haddock templates.
 
     A central index of Haddock API documentation (template cannot use
@@ -1583,7 +1645,8 @@ The following commands are equivalent to ones that would be passed when
 running ``setup haddock``.
 
 .. cfg-field:: haddock-hoogle: boolean
-               --haddock-hoogle
+    :cmdline-opts:
+        --haddock-hoogle
     :synopsis: Generate Hoogle file.
 
     :default: False
@@ -1593,7 +1656,8 @@ running ``setup haddock``.
     This is equivalent to running ``haddock`` with the ``--hoogle`` flag.
 
 .. cfg-field:: haddock-html: boolean
-               --haddock-html
+    :cmdline-opts:
+        --haddock-html
     :synopsis: Build HTML documentation.
 
     :default: True
@@ -1601,7 +1665,8 @@ running ``setup haddock``.
     Build HTML documentation.
 
 .. cfg-field:: haddock-quickjump: boolean
-               --haddock-quickjump
+    :cmdline-opts:
+        --haddock-quickjump
     :synopsis: Generate Quickjump file.
 
     :default: False
@@ -1610,7 +1675,8 @@ running ``setup haddock``.
     This is equivalent to running ``haddock`` with the ``--quickjump`` flag.
 
 .. cfg-field:: haddock-html-location: URL (templated path)
-               --haddock-html-location=URL
+    :cmdline-opts:
+        --haddock-html-location=URL
     :synopsis: Location of HTML documentation for prerequisite packages.
 
     Specify a template for the location of HTML documentation for
@@ -1634,7 +1700,8 @@ running ``setup haddock``.
     using the package tool (e.g. ``ghc-pkg``).
 
 .. cfg-field:: haddock-executables: boolean
-               --haddock-executables
+    :cmdline-opts:
+        --haddock-executables
     :synopsis: Generate documentation for executables.
 
     :default: False
@@ -1642,7 +1709,8 @@ running ``setup haddock``.
     Run haddock on all executable programs.
 
 .. cfg-field:: haddock-tests: boolean
-               --haddock-tests
+    :cmdline-opts:
+        --haddock-tests
     :synopsis: Generate documentation for tests.
 
     :default: False
@@ -1650,7 +1718,8 @@ running ``setup haddock``.
     Run haddock on all test suites.
 
 .. cfg-field:: haddock-benchmarks: boolean
-               --haddock-benchmarks
+    :cmdline-opts:
+        --haddock-benchmarks
     :synopsis: Generate documentation for benchmarks.
 
     :default: False
@@ -1658,7 +1727,8 @@ running ``setup haddock``.
     Run haddock on all benchmarks.
 
 .. cfg-field:: haddock-internal: boolean
-               --haddock-internal
+    :cmdline-opts:
+        --haddock-internal
     :synopsis: Generate documentation for internal modules
 
     :default: False
@@ -1667,7 +1737,8 @@ running ``setup haddock``.
     symbols.
 
 .. cfg-field:: haddock-all: boolean
-               --haddock-all
+    :cmdline-opts:
+        --haddock-all
     :synopsis: Generate documentation for everything
 
     :default: False
@@ -1675,14 +1746,16 @@ running ``setup haddock``.
     Run haddock on all components.
 
 .. cfg-field:: haddock-css: PATH
-               --haddock-css=PATH
+    :cmdline-opts:
+        --haddock-css=PATH
     :synopsis: Location of Haddock CSS file.
 
     The CSS file that should be used to style the generated
     documentation (overriding haddock's default).
 
 .. cfg-field:: haddock-hyperlink-source: boolean
-               --haddock-hyperlink-source
+    :cmdline-opts:
+        --haddock-hyperlink-source
     :synopsis: Generate hyperlinked source code for documentation
 
     :default: False
@@ -1692,14 +1765,16 @@ running ``setup haddock``.
     This is equivalent to running ``haddock`` with the ``--hyperlinked-source`` flag.
 
 .. cfg-field:: haddock-hscolour-css: PATH
-               --haddock-hscolour-css=PATH
+    :cmdline-opts:
+        --haddock-hscolour-css=PATH
     :synopsis: Location of CSS file for HsColour
 
     The CSS file that should be used to style the generated hyperlinked
     source code (from `HsColour`_).
 
 .. cfg-field:: haddock-contents-location: URL
-               --haddock-contents-location=URL
+    :cmdline-opts:
+        --haddock-contents-location=URL
     :synopsis: URL for contents page.
 
     A baked-in URL to be used as the location for the contents page.
@@ -1712,7 +1787,8 @@ running ``setup haddock``.
     There is no command line variant of this flag.
 
 .. cfg-field:: haddock-output-dir: DIR
-               --haddock-output-dir=DIR
+    :cmdline-opts:
+        --haddock-output-dir=DIR
     :synopsis: Generate haddock documentation into this directory.
 
     Generate haddock documentation into this directory instead of the default
@@ -1722,13 +1798,15 @@ running ``setup haddock``.
     next releases.
 
 .. cfg-field:: haddock-use-unicode: boolean
-               --haddock-use-unicode
+    :cmdline-opts:
+        --haddock-use-unicode
     :synopsis: Pass --use-unicode option to haddock.
 
     Generate HTML documentation which contains unicode characters.
 
 .. cfg-field:: haddock-resources-dir: DIR
-               --haddock-resources-dir=DIR
+    :cmdline-opts:
+        --haddock-resources-dir=DIR
     :synopsis: Location of Haddock's static/auxiliary files.
 
     Location of Haddock's static/auxiliary files. For Haddock distributed with
@@ -1737,7 +1815,8 @@ running ``setup haddock``.
     should likely be explicitly set for every Haddock invocation.
 
 .. cfg-field:: open: boolean
-               --open
+    :cmdline-opts:
+        --open
     :synopsis: Open generated documentation in-browser.
 
     When generating HTML documentation, attempt to open it in a browser
@@ -1773,7 +1852,8 @@ Advanced global configuration options
 .. cfg-section:: None
 
 .. cfg-field:: write-ghc-environment-files: always, never, or ghc8.4.4+
-               --write-ghc-environment-files=always|never|ghc8.4.4+
+    :cmdline-opts:
+        --write-ghc-environment-files=always|never|ghc8.4.4+
     :synopsis: Whether a ``.ghc.environment`` should be created after a successful build.
 
     :default: ``never``
@@ -1789,8 +1869,9 @@ Advanced global configuration options
     environment files).
 
 .. cfg-field:: build-info: True, False
-               --enable-build-info
-               --disable-build-info
+    :cmdline-opts:
+        --enable-build-info
+        --disable-build-info
     :synopsis: Whether build information for each individual component should be
                written in a machine readable format.
 
@@ -1816,7 +1897,8 @@ Advanced global configuration options
 
 .. _cmdoption-http-transport:
 .. cfg-field:: http-transport: curl, wget, powershell, or plain-http
-               --http-transport=transport
+    :cmdline-opts:
+        --http-transport=transport
     :synopsis: Transport to use with http(s) requests.
 
     :default: ``curl``
@@ -1832,7 +1914,8 @@ Advanced global configuration options
     search path can only be influenced using :ref:`--extra-prog-path<cmdoption-extra-prog-path>`.
 
 .. cfg-field:: ignore-expiry: boolean
-               --ignore-expiry
+    :cmdline-opts:
+        --ignore-expiry
     :synopsis: Ignore Hackage expiration dates.
 
     :default: False
@@ -1848,7 +1931,8 @@ Advanced global configuration options
     The command line variant of this field is ``--ignore-expiry``.
 
 .. cfg-field:: remote-repo-cache: directory
-               --remote-repo-cache=DIR
+    :cmdline-opts:
+        --remote-repo-cache=DIR
     :synopsis: Location of packages cache.
 
     :default: ``~/.cabal/packages``
@@ -1860,7 +1944,8 @@ Advanced global configuration options
     ``--remote-repo-cache=DIR``.
 
 .. cfg-field:: logs-dir: directory
-               --logs-dir=DIR
+    :cmdline-opts:
+        --logs-dir=DIR
     :synopsis: Directory to store build logs.
 
     :default: ``~/.cabal/logs``
@@ -1871,7 +1956,8 @@ Advanced global configuration options
     The command line variant of this flag is ``--logs-dir=DIR``.
 
 .. cfg-field:: build-summary: template filepath
-               --build-summary=TEMPLATE
+    :cmdline-opts:
+        --build-summary=TEMPLATE
     :synopsis: Build summaries location.
 
     :default: ``~/.cabal/logs/build.log``
@@ -1893,7 +1979,8 @@ Advanced solver options
 Most users generally won't need these.
 
 .. cfg-field:: solver: SOLVER
-               --solver=SOLVER
+    :cmdline-opts:
+        --solver=SOLVER
     :synopsis: Which solver to use.
 
     This field is reserved to allow the specification of alternative
@@ -1903,7 +1990,8 @@ Most users generally won't need these.
     The command line variant of this field is ``--solver=modular``.
 
 .. cfg-field:: max-backjumps: nat
-               --max-backjumps=N
+    :cmdline-opts:
+        --max-backjumps=N
     :synopsis: Maximum number of solver backjumps.
 
     :default: 4000
@@ -1915,8 +2003,9 @@ Most users generally won't need these.
     The command line variant of this field is ``--max-backjumps=4000``.
 
 .. cfg-field:: reorder-goals: boolean
-               --reorder-goals
-               --no-reorder-goals
+    :cmdline-opts:
+        --reorder-goals
+        --no-reorder-goals
     :synopsis: Allow solver to reorder goals.
 
     :default: False
@@ -1930,8 +2019,9 @@ Most users generally won't need these.
     The command line variant of this field is ``--(no-)reorder-goals``.
 
 .. cfg-field:: count-conflicts: boolean
-               --count-conflicts
-               --no-count-conflicts
+    :cmdline-opts:
+        --count-conflicts
+        --no-count-conflicts
     :synopsis: Solver prefers versions with less conflicts.
 
     :default: True
@@ -1943,8 +2033,9 @@ Most users generally won't need these.
     ``--(no-)count-conflicts``.
 
 .. cfg-field:: fine-grained-conflicts: boolean
-               --fine-grained-conflicts
-               --no-fine-grained-conflicts
+    :cmdline-opts:
+        --fine-grained-conflicts
+        --no-fine-grained-conflicts
     :synopsis: Skip a version of a package if it does not resolve any conflicts
                encountered in the last version (solver optimization).
 
@@ -1960,8 +2051,9 @@ Most users generally won't need these.
     ``--(no-)fine-grained-conflicts``.
 
 .. cfg-field:: minimize-conflict-set: boolean
-               --minimize-conflict-set
-               --no-minimize-conflict-set
+    :cmdline-opts:
+        --minimize-conflict-set
+        --no-minimize-conflict-set
     :synopsis: Try to improve the solver error message when there is no
                solution.
 
@@ -1975,8 +2067,9 @@ Most users generally won't need these.
     ``--(no-)minimize-conflict-set``.
 
 .. cfg-field:: strong-flags: boolean
-               --strong-flags
-               --no-strong-flags
+    :cmdline-opts:
+        --strong-flags
+        --no-strong-flags
     :synopsis: Do not defer flag choices when solving.
 
     :default: False
@@ -1986,8 +2079,9 @@ Most users generally won't need these.
     The command line variant of this field is ``--(no-)strong-flags``.
 
 .. cfg-field:: allow-boot-library-installs: boolean
-               --allow-boot-library-installs
-               --no-allow-boot-library-installs
+    :cmdline-opts:
+        --allow-boot-library-installs
+        --no-allow-boot-library-installs
     :synopsis: Allow cabal to install or upgrade any package.
 
     :default: False
@@ -2001,7 +2095,8 @@ Most users generally won't need these.
     ``--(no-)allow-boot-library-installs``.
 
 .. cfg-field:: cabal-lib-version: VERSION
-               --cabal-lib-version=VERSION
+    :cmdline-opts:
+        --cabal-lib-version=VERSION
     :synopsis: Version of Cabal library used to build package.
 
     This field selects the version of the Cabal library which should be
@@ -2014,8 +2109,9 @@ Most users generally won't need these.
     ``--cabal-lib-version=1.24.0.1``.
 
 .. cfg-field:: prefer-oldest: boolean
-               --prefer-oldest
-               --no-prefer-oldest
+    :cmdline-opts:
+        --prefer-oldest
+        --no-prefer-oldest
     :synopsis: Prefer the oldest versions of packages available.
     :since:    3.10
 
diff --git a/doc/cabaldomain.py b/doc/cabaldomain.py
index 9b0f1e004f2..a3691429c1e 100644
--- a/doc/cabaldomain.py
+++ b/doc/cabaldomain.py
@@ -69,9 +69,6 @@
 
    References field added by `.. cfg-field`.
 
-.. rst::role:: cfg-flag
-
-   References flag added by `.. cfg-field`.
 
 
 All roles can be supplied with title as in standard sphinx references::
@@ -135,29 +132,6 @@ def parse_deprecated(txt):
     except ValueError:
         return True
 
-def parse_flag(env, sig, signode):
-    import re
-    names = []
-    for i, flag in enumerate(sig.split(',')):
-        flag = flag.strip()
-        sep = '='
-        parts = flag.split('=')
-        if len(parts) == 1:
-            sep=' '
-            parts = flag.split()
-        if len(parts) == 0: continue
-
-        name = parts[0]
-        names.append(name)
-        sig = sep + ' '.join(parts[1:])
-        sig = re.sub(r'<([-a-zA-Z ]+)>', r'⟨\1⟩', sig)
-        if i > 0:
-            signode += addnodes.desc_name(', ', ', ')
-        signode += addnodes.desc_name(name, name)
-        if len(sig) > 0:
-            signode += addnodes.desc_addname(sig, sig)
-
-    return names[0]
 
 
 class Meta(object):
@@ -592,34 +566,94 @@ def run(self):
 class ConfigField(CabalField):
     section_key = 'cabal:cfg-section'
     indextemplate = '%s ; cabal project option'
+    option_spec = dict(CabalField.option_spec,
+                       **{'cmdline-opts': lambda x: x})
+
+    def get_signatures(self):
+        signatures = super(ConfigField, self).get_signatures()
+        self.command_line_options = self._parse_cmdline_opts(self.options.get('cmdline-opts'))
+
+        non_option_signatures = [
+            signature for signature in signatures
+            if signature.strip() and not signature.strip().startswith('-')
+        ]
+
+        # Keep only the primary cfg-field signature and render command-line
+        # variants as links to standard command-line options.
+        if non_option_signatures:
+            return [non_option_signatures[0]]
+
+        return signatures
+
+    def _parse_cmdline_opts(self, text):
+        if not text:
+            return []
+
+        labels = [line.strip() for line in text.splitlines() if line.strip().startswith('-')]
+        if not labels:
+            return []
+
+        first_long_target = None
+        for label in labels:
+            if label.startswith('--'):
+                first_long_target = label.split('[', 1)[0].split('=', 1)[0]
+                break
+
+        options = []
+        last_long_target = None
+        for label in labels:
+            if label.startswith('--'):
+                target = label.split('[', 1)[0].split('=', 1)[0]
+                last_long_target = target
+            else:
+                target = last_long_target or first_long_target or label.split('[', 1)[0].split('=', 1)[0]
+            options.append((label, target))
+
+        return options
+
     def handle_signature(self, sig, signode):
-        sig = sig.strip()
-        if sig.startswith('-'):
-            name = parse_flag(self, sig, signode)
-        else:
-            name = super(ConfigField, self).handle_signature(sig, signode)
+        return super(ConfigField, self).handle_signature(sig.strip(), signode)
 
-        return name
+    def _make_command_line_options_block(self, options):
+        block = nodes.container(classes=['cabal-cmdline-opts'])
+
+        for label, target in options:
+            line = nodes.paragraph(classes=['cabal-cmdline-option'])
+            line += nodes.inline('$ ', '$ ', classes=['cabal-cmdline-icon'])
+
+            refnode = addnodes.pending_xref('',
+                                            refdomain='std',
+                                            reftype='option',
+                                            reftarget=target,
+                                            refwarn=False)
+            refnode += nodes.literal(label, label)
+            line += refnode
+            block += line
+
+        return block
+
+    def run(self):
+        result = super(ConfigField, self).run()
+        options = getattr(self, 'command_line_options', [])
+        if not options:
+            return result
+
+        for item in result:
+            if not isinstance(item, addnodes.desc):
+                continue
+
+            for desc_item in item:
+                if isinstance(desc_item, addnodes.desc_content):
+                    desc_item.insert(0, self._make_command_line_options_block(options))
+                    return result
+
+        return result
 
     def get_index_entry(self, env, name):
-        if name.startswith('-'):
-            section = self.env.ref_context.get(self.section_key)
-            if section is not None:
-                parts = ('cfg-flag', section, name)
-                indexname = section + ':' + name
-            else:
-                parts = ('cfg-flag', name)
-                indexname = name
-            indexentry = name + '; cabal project option'
-            targetname = '-'.join(parts)
-            return indexentry, targetname
-        else:
-            return super(ConfigField,self).get_index_entry(env, name)
+        return super(ConfigField,self).get_index_entry(env, name)
 
     def get_env_key(self, env, name):
         section = self.env.ref_context.get(self.section_key)
-        if name.startswith('-'):
-            return (section, name), 'cfg-flags'
         return (section, name), 'cfg-fields'
 
 class CabalConfigFieldXRef(CabalFieldXRef):
@@ -694,7 +728,6 @@ def generate(self, docnames=None):
 
         # (title, section store, fields store)
         entries = [('cabal.project fields', 'cfg-section', 'cfg-field'),
-                   ('cabal project flags', 'cfg-section', 'cfg-flag'),
                    ('package.cabal fields', 'pkg-section', 'pkg-field')]
 
         result = []
@@ -744,7 +777,7 @@ def make_data_keys(typ, target, node):
         section = node.get('cabal:pkg-section')
         return [(section, target),
                 (None, target)]
-    elif typ in ('cfg-field', 'cfg-flag'):
+    elif typ == 'cfg-field':
         section = node.get('cabal:cfg-section')
         return [(section, target), (None, target)]
     else:
@@ -810,9 +843,7 @@ def make_title(typ, key, meta):
         section, name = key
         return "cabal.project " + name + " field " + render_meta_title(meta)
 
-    elif typ == 'cfg-flag':
-        section, name = key
-        return "cabal flag " + name + " " + render_meta_title(meta)
+
 
     else:
         raise ValueError("Unknown type: " + typ)
@@ -865,7 +896,6 @@ class CabalDomain(Domain):
         'pkg-field'  : CabalPackageFieldXRef(warn_dangling=True),
         'cfg-section': XRefRole(warn_dangling=True),
         'cfg-field'  : CabalConfigFieldXRef(warn_dangling=True),
-        'cfg-flag'   : CabalConfigFieldXRef(warn_dangling=True),
     }
     initial_data = {
         'pkg-sections': {},
@@ -874,7 +904,6 @@ class CabalDomain(Domain):
         'index-num'   : {}, #per document number of objects
                             # used to order references page
         'cfg-fields'  : {},
-        'cfg-flags'   : {},
     }
     indices = [
         ConfigFieldIndex
@@ -884,11 +913,10 @@ class CabalDomain(Domain):
         'pkg-field'  : 'pkg-fields',
         'cfg-section': 'cfg-sections',
         'cfg-field'  : 'cfg-fields',
-        'cfg-flag'   : 'cfg-flags',
     }
     def clear_doc(self, docname):
         for k in ['pkg-sections', 'pkg-fields', 'cfg-sections',
-                  'cfg-fields', 'cfg-flags']:
+                  'cfg-fields']:
             to_del = []
             for name, (fn, _, _) in self.data[k].items():
                 if fn == docname:
@@ -918,7 +946,7 @@ def get_objects(self):
         Used for search functionality
         '''
         for typ in ['pkg-section', 'pkg-field',
-                    'cfg-section', 'cfg-field', 'cfg-flag']:
+                    'cfg-section', 'cfg-field']:
             key = self.types[typ]
             for name, (fn, target, meta) in self.data[key].items():
                 title = make_title(typ, name, meta)
diff --git a/doc/conf.py b/doc/conf.py
index 671aa2adfde..eea05cf8784 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -69,7 +69,8 @@
 html_title = "Cabal {} User's Guide".format(release)
 html_short_title = "Cabal %s User's Guide" % release
 html_logo = 'images/Cabal-dark.png'
-html_static_path = ['images']
+html_static_path = ['images', '_static']
+html_css_files = ['css/custom.css']
 # Convert quotes and dashes to typographically correct entities
 html_use_smartypants = True
 html_show_copyright = True