Fix broken links

mpilgrem · mpilgrem · commit efda48f0e471 · 2024-07-21T01:50:57.000+01:00
diff --git a/doc/commands/config_command.md b/doc/commands/config_command.md
@@ -38,7 +38,7 @@ The command also accepts flags and options of the
 [`stack build`](build_command.md#flags-affecting-ghcs-behaviour) command that
 affect the location of the local project installation directory, such as
 `--profile` and `--no-strip`. For further information, see the documentation of
-the [project Stack work directory](stack_work.md#project-stack-work-directory).
+the [project Stack work directory](../topics/stack_work.md).
 
 ## The `stack config set` commands
 
diff --git a/doc/commands/docker_command.md b/doc/commands/docker_command.md
@@ -14,8 +14,8 @@ Stack is able to build your code inside a Docker image, which means even more
 reproducibility to your builds, since you and the rest of your team will always
 have the same system libraries.
 
-For further information, see the [Docker integration](docker_integration.md)
-documentation.
+For further information, see the
+[Docker integration](../topics/docker_integration.md) documentation.
 
 ## The `stack docker pull` command
 
diff --git a/doc/commands/exec_command.md b/doc/commands/exec_command.md
@@ -69,4 +69,4 @@ The command also accepts flags and options of the
 [`stack build`](build_command.md#flags-affecting-ghcs-behaviour) command that
 affect the location of the local project installation directory, such as
 `--profile` and `--no-strip`. For further information, see the documentation of
-the [project Stack work directory](stack_work.md#project-stack-work-directory).
+the [project Stack work directory](../topics/stack_work.md).
diff --git a/doc/commands/index.md b/doc/commands/index.md
@@ -3,7 +3,7 @@
 # Commands (advanced)
 
 Some of Stack's features will not be needed regularly or by all users. This part
-of the guide and the part on [configuration](configure/index.md) provide
+of the guide and the part on [configuration](../configure/index.md) provide
 information about somethose features, organised as a reference guide. Some of
 the features are complex and separate pages are dedicated to them.
 
@@ -14,8 +14,8 @@ the features are complex and separate pages are dedicated to them.
 * [`setup`](setup_command.md) - get GHC for a Stack project (usually not needed)
 * [`update`](update_command.md) - update the package index (usually not needed)
 * [`new`](new_command.md) - create a new project with Stack
-* [`init`](init_command.md) - initialise Stack's project-level YAML configuration file for an
-  existing project
+* [`init`](init_command.md) - initialise Stack's project-level YAML
+  configuration file for an existing project
 
 ### Building
 
@@ -79,8 +79,8 @@ the features are complex and separate pages are dedicated to them.
 
 * [`hoogle`](hoogle_command.md) - run `hoogle`
 * [`dot`](dot_command.md) - dependency visualization
-* [`hpc`](hpc_command.md) - generate Haskell Program Coverage (HPC) code coverage
-  reports
+* [`hpc`](hpc_command.md) - generate Haskell Program Coverage (HPC) code
+  coverage reports
 
 ### Managing Stack versions
 
@@ -100,14 +100,14 @@ Stack's commands are listed below, in alphabetical order.
 * [`exec`](exec_command.md) - executate a command in the Stack environment
 * [`haddock`](build_command.md) - a synonym for `stack build --haddock`
 * [`hoogle`](hoogle_command.md) - run `hoogle`
-* [`hpc`](hpc_command.md) - generate Haskell Program Coverage (HPC) code coverage
-  reports
+* [`hpc`](hpc_command.md) - generate Haskell Program Coverage (HPC) code
+  coverage reports
 * [`ghc`](ghc_command.md) - run `ghc`
 * [`ghci`](ghci_command.md) - run GHCi, a REPL environment
 * [`ide`](ide_command.md) - information for an integrated development
   environment (IDE)
-* [`init`](init_command.md) - initialise Stack's project-level YAML configuration file for an
-  existing project
+* [`init`](init_command.md) - initialise Stack's project-level YAML
+  configuration file for an existing project
 * [`install`](build_command.md) - a synonym for `stack build --copy-bins`
 * [`list`](list_command.md) - list packages on Hackage or in a snapshot
 * [`ls`](ls_command.md) - list information about Stack
diff --git a/doc/commands/path_command.md b/doc/commands/path_command.md
@@ -46,4 +46,4 @@ The command also accepts flags and options of the
 [`stack build`](build_command.md#flags-affecting-ghcs-behaviour) command that
 affect the location of the local project installation directory, such as
 `--profile` and `--no-strip`. For further information, see the documentation of
-the [project Stack work directory](stack_work.md#project-stack-work-directory).
+the [project Stack work directory](../topics/stack_work.md).
diff --git a/doc/commands/script_command.md b/doc/commands/script_command.md
@@ -203,7 +203,7 @@ outputs will be written to a directory named `MyScript.hs` at
 
 As for Example 1, but `acme-missiles-0.2` is specified by adding it to the
 snapshot as an extra-dep. The `stack script` command is specified using Stack's
-[script interpreter](scripts.md).
+[script interpreter](../topics/scripts.md).
 
 ~~~haskell
 {- stack script
@@ -244,7 +244,7 @@ Consequently, for example, Stack will:
 Consider also the following script extract, based on snapshot Stackage
  LTS Haskell 20.25, where considerations on Windows differ from non-Windows. The
 `stack script` command is specified using Stack's
-[script interpreter](scripts.md).
+[script interpreter](../topics/scripts.md).
 
 === "Windows"
 
diff --git a/doc/configure/global_flags.md b/doc/configure/global_flags.md
@@ -41,14 +41,14 @@ documentation.
 
 Pass the option `--custom-preprocessor-extensions <extension>` to specify an
 extension used for a custom preprocessor. For further information, see the
-documentation for the corresponding non-project specific configuration
+documentation for the corresponding project specific configuration
 [option](yaml/project.md#custom-preprocessor-extensions).
 
 ## `--docker*` flags and options
 
 Stack supports automatically performing builds inside a Docker container. For
 further information see `stack --docker-help` or the
-[Docker integratiom](docker_integration.md) documentation.
+[Docker integration](../topics/docker_integration.md) documentation.
 
 ## `--[no-]dump-logs` flag
 
@@ -154,7 +154,8 @@ see the documentation for the corresponding non-project specific configuration
 ## `--nix*` flags and options
 
 Stack can be configured to integrate with Nix. For further information, see
-`stack --nix-help` or the [Nix integration](nix_integration.md) documentation.
+`stack --nix-help` or the [Nix integration](../topics/nix_integration.md)
+documentation.
 
 ## `--numeric-version` flag
 
@@ -222,7 +223,7 @@ corresponding non-project specific configuration
 [:octicons-tag-24: 2.15.1](https://github.com/commercialhaskell/stack/releases/tag/v2.15.1)
 
 Pass the option `--snapshot <snapshot>` to specify the snapshot. For further
-information, see the [YAML configuration](yaml_configuration.md#snapshot)
+information, see the [YAML configuration](yaml/project.md#snapshot)
 documentation.
 
 At the command line (only):
@@ -322,7 +323,7 @@ non-project specific configuration [option](yaml/non-project.md#with-hpack).
 Default: `.stack-work`
 
 Overrides: [`STACK_WORK`](environment_variables.md#stack_work) environment
-variable, and [`work-dir`](yaml_configuration.md) non-project specific
+variable, and [`work-dir`](yaml/non-project.md#work-dir) non-project specific
 configuration option.
 
 Pass the option `--work-dir <relative_path_to_the_Stack_root>` to specify the
diff --git a/doc/configure/index.md b/doc/configure/index.md
@@ -23,7 +23,7 @@ Stack is configured by the content of YAML files. A global YAML configuration
 file contains non-project specific options. A project-level YAML configuration
 file contains project-specific options and may contain non-project specific
 options. For further information, see the
-[YAML configuration](yaml_configuration.md) documentation.
+[YAML configuration](yaml/yaml_configuration.md) documentation.
 
 ## Global flags and options
 
diff --git a/doc/configure/yaml/non-project.md b/doc/configure/yaml/non-project.md
@@ -539,7 +539,8 @@ Command line equivalents: `--docker-*` flags and options (see
 `stack --docker-help` for details).
 
 For further information, see the
-[Docker integration](docker_integration.md#configuration) documentation.
+[Docker integration](../../topics/docker_integration.md#configuration)
+documentation.
 
 ## dump-logs
 
@@ -896,7 +897,7 @@ Command line equivalents: `--nix-*` flags and options (see `stack --nix-help`
 for details).
 
 For further information, see the
-[Nix integration](nix_integration.md#configuration) documentation.
+[Nix integration](../../topics/nix_integration.md#configuration) documentation.
 
 ## notify-if-arch-unknown
 
@@ -1406,8 +1407,8 @@ stack-developer-mode: false
 
 ## system-ghc
 
-Default: `false`, unless the [Docker](docker_integration.md) or
-[Nix](nix_integration.md) integration is enabled.
+Default: `false`, unless the [Docker](../../topics/docker_integration.md) or
+[Nix](../../topics/nix_integration.md) integration is enabled.
 
 Command line equivalent (takes precedence): `--[no-]system-ghc` flag
 
@@ -1533,7 +1534,7 @@ Command line equivalent (takes precedence):
 [`--work-dir`](../global_flags.md#-work-dir-option) option
 
 Environment variable alternative (lowest precedence):
-[`STACK_WORK`](environment_variables.md#stack_work)
+[`STACK_WORK`](../environment_variables.md#stack_work)
 
 `work-dir` specifies the path of Stack's work directory, within a local project
 or package directory. The path must be a relative one, relative to the
diff --git a/doc/configure/yaml/project.md b/doc/configure/yaml/project.md
@@ -44,7 +44,7 @@ currently four snapshot types:
 * No snapshot, just use packages shipped with the compiler. For GHC this looks
   like `snapshot: ghc-9.6.5`
 * Custom snapshot, via a URL or relative file path. For further information, see
-  the [snapshot and package location](pantry.md) documentation.
+  the [snapshot and package location](../../topics/pantry.md) documentation.
 
 Each of these snapshots will also determine what constraints are placed on the
 compiler version. See the [compiler-check](non-project.md#compiler-check) option
@@ -122,7 +122,7 @@ A Pantry package location is one or three different kinds of sources:
 * a Git or Mercurial repository.
 
 For further information on the format for specifying a Pantry package location,
-see the [Pantry](pantry.md) documentation. For example:
+see the [Pantry](../../topics/pantry.md) documentation. For example:
 
 ~~~yaml
 extra-deps:
diff --git a/doc/configure/yaml/yaml_configuration.md b/doc/configure/yaml/yaml_configuration.md
@@ -20,10 +20,9 @@ Stack is configured by the content of YAML files.
 ## YAML configuration
 
 Stack's YAML configuration options break down into
-[project-specific](#project-specific-configuration) options and
-[non-project-specific](#non-project-specific-configuration) options. The former
-are configured at the project level. The latter are configured at the project
-level or globally.
+[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.
 
 The **project-level** configuration file (`stack.yaml`, by default) contains
 project-specific options and may contain non-project-specific options. However,
@@ -49,8 +48,8 @@ option set in the system-wide file (if it exists).
 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
-[`STACK_CONFIG`](environment_variables.md#stack_config) and
-[`STACK_GLOBAL_CONFIG`](environment_variables.md#stack_config) environment
+[`STACK_CONFIG`](../environment_variables.md#stack_config) and
+[`STACK_GLOBAL_CONFIG`](../environment_variables.md#stack_config) environment
 variables, respectively.
 
 === "Unix-like"
@@ -96,4 +95,5 @@ 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](stack_yaml_vs_cabal_package_file.md) documentation.
+[stack.yaml vs a Cabal file](../../topics/stack_yaml_vs_cabal_package_file.md)
+documentation.
diff --git a/doc/faq.md b/doc/faq.md
@@ -338,8 +338,8 @@ stack build
 ## I heard you can use this with Docker?
 
 Yes, Stack supports using Docker with images that contain preinstalled Stackage
-packages and the tools. See [Docker integration](docker_integration.md) for
-details.
+packages and the tools. See [Docker integration](topics/docker_integration.md)
+for details.
 
 ## How do I build a statically-linked executable on Linux?
 
diff --git a/doc/topics/CI.md b/doc/topics/CI.md
@@ -6,7 +6,7 @@
 
 The Stack repository uses GitHub Actions for its own CI. For further
 information, see the guide to
-[contributing](CONTRIBUTING.md#continuous-integration-ci).
+[contributing](../CONTRIBUTING.md#continuous-integration-ci).
 
 ## Azure
 
diff --git a/doc/topics/Stack_and_VS_Code.md b/doc/topics/Stack_and_VS_Code.md
@@ -35,11 +35,12 @@ each version of HLS that the extension needs is on the PATH.
 
 For the most part, the versions of HLS provided by GHCup are built with the same
 versions of GHC that Stack downloads from its default `setup-info` dictionary
-(see [YAML configuration: setup-info](yaml_configuration.md)). Stack's default
-is to mirror the 'official' binary distributions published by GHC. However, in
-some cases, it is possible that a GHCup-supplied and GHCup-selected HLS has been
-built with a different binary distribution of GHC than the one which Stack has
-installed.
+(see
+[YAML configuration: setup-info](../configure/yaml/non-project.md#setup-info)).
+Stack's default is to mirror the 'official' binary distributions published by
+GHC. However, in some cases, it is possible that a GHCup-supplied and
+GHCup-selected HLS has been built with a different binary distribution of GHC
+than the one which Stack has installed.
 
 One example of that occurred with the release of GHC 9.0.2. For some Linux users
 (Debian 9 and Fedora 27), the version of GHC 9.0.2 linked on GHC’s download
@@ -61,17 +62,17 @@ GHC, GHCup takes over obtaining and installing that version. By default, the
 script to install GHCup (which can be run more than once) configures Stack in
 that way. For further information about how GHCup configures Stack, see the GHC
 installation customisation
-[documentation](../configure/yaml/non-project.md#ghc-installation-customisation).
+[documentation](../configure/customisation_scripts.md#ghc-installation-customisation).
 
 ### Workaround #1
 
 If GHCup does not configure Stack in the way described above, one workaround is
 to allow GHCup to install versions of GHC on the PATH and to cause Stack to use
 those versions of GHC, by making use of Stack's `install-ghc` option (which
 needs to be disabled) and Stack's `system-ghc` option (which needs to be
-enabled). For further information about these options, see the `install-ghc`
-[documentation](../configure/yaml/non-project.md#install-ghc) and the `system-ghc`
-[documentation](../configure/yaml/non-project.md#system-ghc).
+enabled). For further information about these options, see the
+[`install-ghc`](../configure/yaml/non-project.md#install-ghc) documentation and
+the [`system-ghc`](../configure/yaml/non-project.md#system-ghc) documentation.
 
 For this workaround to work, each time that a snapshot is used that references a
 different version of GHC, then GHCup must be used to install it (if GHCup has
diff --git a/doc/topics/editor_integration.md b/doc/topics/editor_integration.md
@@ -17,4 +17,4 @@ eval "$(stack --bash-completion-script stack)"
 ~~~
 
 For more information and other shells, see the
-[Shell auto-completion wiki page](https://docs.haskellstack.org/en/stable/shell_autocompletion)
+[shell auto-completion](shell_autocompletion.md) documentation.
diff --git a/doc/topics/stack_root.md b/doc/topics/stack_root.md
@@ -17,9 +17,10 @@ configured to use the XDG Base Directory Specification, and/or whether an
 alternative location to Stack's default 'programs' directory has been specified.
 
 The location of the Stack root can be configured by setting the
-[`STACK_ROOT`](environment_variables.md#stack_root) environment variable or
-using Stack's [`--stack-root`](../configure/global_flags.md#stack-root-option)
-option on the command line.
+[`STACK_ROOT`](../configure/environment_variables.md#stack_root) environment
+variable or using Stack's
+[`--stack-root`](../configure/global_flags.md#stack-root-option) option on the
+command line.
 
 === "Unix-like"
 
diff --git a/doc/topics/stack_work.md b/doc/topics/stack_work.md
@@ -15,7 +15,7 @@ By default, Stack work directories are named `.stack-work`. The name can be
 overidden by:
 
 * the use of the
-  [`STACK_WORK` environment variable](environment_variables.md#stack_work);
+  [`STACK_WORK` environment variable](../configure/environment_variables.md#stack_work);
 * the [`work-dir`](../configure/yaml/non-project.md#work-dir) non-project
   specific configuration option; or
 * the [`--work-dir`](../configure/global_flags.md#-work-dir-option) command line
diff --git a/doc/tutorial/cabal_flags_and_ghc_options.md b/doc/tutorial/cabal_flags_and_ghc_options.md
@@ -91,9 +91,9 @@ of reproducible builds is - in the Stack maintainers' views - worth the
 confusion.
 
 Final point: if you have GHC options that you'll be regularly passing to your
-packages, you can add them to your `stack.yaml` file. See the
-[documentation section on ghc-options](yaml_configuration.md#ghc-options)
-for more information.
+packages, you can add them to your `stack.yaml` file. For more information, see
+the [ghc-options](../configure/yaml/non-project.md#ghc-options) non-project
+specific configuration option documentation.
 
 !!! note
 
diff --git a/doc/tutorial/index.md b/doc/tutorial/index.md
@@ -54,9 +54,9 @@ used for building Haskell code, such as Cabal (the tool).
 
 ## Downloading and Installation
 
-The [documentation dedicated to downloading Stack](install_and_upgrade.md) has
-the most up-to-date information for a variety of operating systems. Instead of
-repeating that content here, please go check out that page and come back here
+The [documentation dedicated to downloading Stack](../install_and_upgrade.md)
+has the most up-to-date information for a variety of operating systems. Instead
+of repeating that content here, please go check out that page and come back here
 when you can successfully run `stack --version`.
 
 We also assume that the directory reported by `stack path --local-bin` has been
diff --git a/doc/tutorial/installed_package_databases.md b/doc/tutorial/installed_package_databases.md
@@ -90,7 +90,7 @@ The reason we have this structure is that:
 
 As you probably guessed, there can be multiple snapshot databases available. See
 the contents of the `snapshots` directory in the
-[Stack root](../../topics/stack_root.md).
+[Stack root](../topics/stack_root.md).
 
 * On Unix-like operating systems, each snapshot is in the last of a sequence of
   three subdirectories named after the platform, a 256-bit hash of the source
diff --git a/doc/tutorial/multi-package _projects.md b/doc/tutorial/multi-package _projects.md
diff --git a/doc/tutorial/stack_build_synoynms.md b/doc/tutorial/stack_build_synoynms.md
diff --git a/mkdocs.yml b/mkdocs.yml
