Merge branch 'stable'

Author: mpilgrem

doc/configure/yaml/yaml_configuration.md

@@ -1,33 +1,68 @@
 <div class="hidden-warning"><a href="https://docs.haskellstack.org/"><img src="https://cdn.jsdelivr.net/gh/commercialhaskell/stack/doc/img/hidden-warning.svg"></a></div>
 
-# Configuration and customisation
+# Configuration
 
-Stack is configured by the content of YAML files.
+Stack is configured by the content of [YAML](https://yaml.org/) files.
 
-!!! info
+## Project-specific and non-project specific options
 
-    A Haskell package is an organised collection of Haskell code and related
-    files. It is described by a Cabal file or a `package.yaml` file (which can
-    be used to generate a Cabal file). The package description is itself part of
-    the package. Its file is located in the root directory of a project package
-    or dependency located locally.
+Stack's configuration options are each of one of two types:
 
-    A Stack project is a local directory that contains a Stack project-level
-    configuration file (`stack.yaml`, by default). A project may relate to more
-    than one project package. A single-package project's directory will usually
-    also be the project package's root directory.
+<div class="grid cards" markdown>
 
-## YAML configuration
+-   :material-account:{ .lg .middle } __Project-specific__
 
-Stack's YAML configuration options break down into
-[project-specific](project.md) options and
-[non-project-specific](non-project.md) options. The former are configured at the
-project level. The latter are configured at the project level or globally.
+    Configured at the project level
 
-The **project-level** configuration file (`stack.yaml`, by default) contains
-project-specific options and may contain non-project-specific options. However,
-non-project-specific options in the project-level configuration file in the
-`global-project` directory (see below) are ignored by Stack.
+    ---
+
+    [:octicons-arrow-right-24: Learn more](project.md)
+
+-   :material-account-multiple:{ .lg .middle } __Non-project specific__
+
+    Configured globally or at the project level.
+
+    ---
+
+    [:octicons-arrow-right-24: Learn more](non-project.md)
+
+</div>
+
+## Project-level and global configuration files
+
+Stack's configuration files are each of one of two types:
+
+<div class="grid cards" markdown>
+
+-   :material-language-haskell:{ .lg .middle } __Project-level__
+
+    Named `stack.yaml` by default.
+
+    ---
+
+    Contains [project-specific](project.md) options and may contain
+    [non-project-specific](non-project.md) options.
+
+    Non-project-specific options in the project-level configuration file in the
+    `global-project` directory (see below) are ignored by Stack.
+
+-   :octicons-globe-24:{ .lg .middle } __Global__
+
+    Named `config.yaml`.
+
+    There is a user-specific file and there may be a system-wide one. If a
+    user-specific file does not exist, then Stack will create one.
+
+    ---
+
+    Contains [non-project-specific](non-project.md) options.
+
+    An option set in the user-specific file will override a corresponding option
+    set in the system-wide file (if it exists).
+
+</div>
+
+## Location of project-level configuration
 
 Stack obtains project-level configuration from one of the following (in order of
 preference):
@@ -38,16 +73,13 @@ preference):
 4. A file name `stack.yaml` in the `global-project` directory in the
    [Stack root](../../topics/stack_root.md).
 
-The **global** configuration files (`config.yaml`) contain only
-non-project-specific options. There is a user-specific global confguration file
-and there may be an optional system-wide global configuration file. If a
-user-specific global configuration file does not exist, then Stack will create
-one. An option set in the user-specific file will override a corresponding
-option set in the system-wide file (if it exists).
+## Location of global configuration
 
-The default location of these files depends on the operating system and, in the
-case of the user-specific file, whether Stack is configured to use the XDG Base
-Directory Specification. An absolute path to these files can be specified by the
+The default location of global configuration files depends on the operating
+system and, in the case of the user-specific file, whether Stack is configured
+to use the XDG Base Directory Specification.
+
+An absolute path to these files can be specified by the
 [`STACK_CONFIG`](../environment_variables.md#stack_config) and
 [`STACK_GLOBAL_CONFIG`](../environment_variables.md#stack_config) environment
 variables, respectively.
@@ -88,12 +120,3 @@ variables, respectively.
     the `XDG_CONFIG_HOME` environment variable does not exist, the default is
     `~/.config/stack` on Unix-like operating systems and `%APPDIR%\stack` on
     Windows.
-
-This page is intended to document fully all YAML configuration options. If you
-identify any inaccuracies or incompleteness, please update the page, and if
-you're not sure how, open an issue labeled "question".
-
-If you wish to understand the difference between a `stack.yaml` files and a
-Cabal file (named `<package_name>.cabal`), see the
-[stack.yaml vs a Cabal file](../../topics/stack_yaml_vs_cabal_package_file.md)
-documentation.