Merge branch 'stable'

Author: mpilgrem

CONTRIBUTING.md

@@ -122,9 +122,11 @@ extensions.
 
 Those files are rendered on [haskellstack.org](http://haskellstack.org) by
 [Read the Docs](https://readthedocs.org/) using
-[MkDocs](https://www.mkdocs.org/). The `stable` branch of the repository
-provides the 'stable' version of the online documentation. The `master` branch
-provides the 'latest' version of the documentation.
+[MkDocs](https://www.mkdocs.org/) and the
+[Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme. The
+`stable` branch of the repository provides the 'stable' version of the online
+documentation. The `master` branch provides the 'latest' version of the
+documentation.
 
 The 'stable' version of the online documentation is intended to be applicable to
 the latest released version of Stack. If you would like to help with that
@@ -138,13 +140,22 @@ from the content of files at the point in the responsitory's history specified
 by the corresponding release tag. Consequently, that content is fixed once
 released.
 
-The Markdown syntax supported by MkDocs can differ from the GitHub Flavored
-Markdown ([GFM](https://github.github.com/gfm/)) supported for content on
-GitHub.com. Please refer to the
+The Markdown syntax supported by MkDocs and the Material for MkDocs theme can
+differ from the GitHub Flavored Markdown ([GFM](https://github.github.com/gfm/))
+supported for content on GitHub.com. Please refer to the
 [MkDocs documentation](https://www.mkdocs.org/user-guide/writing-your-docs/#writing-with-markdown)
+and the
+[Material for MkDocs reference](https://squidfunk.github.io/mkdocs-material/reference/)
 to ensure your pull request will achieve the desired rendering.
 
-The configuration file for MkDocs is `mkdocs.yml`.
+The configuration file for MkDocs is `mkdocs.yml`. The extensions to the basic
+Markdown syntax used include:
+
+* admonitions
+* code blocks, with syntax highlighting provided by
+  [Pygments](https://pygments.org/)
+* content tabs, which can be nested
+* icons and emojis
 
 The files in the `doc` directory of the repository include two symbolic links
 (symlinks), `ChangeLog.md` and `CONTRIBUTING.md`. Users of Git on Windows should

doc/GUIDE_advanced.md

@@ -18,7 +18,7 @@ quit.
 
 ## The `stack --[no-]rsl-in-log` flag
 
-(Since 2.7.6)
+[:octicons-tag-24: 2.7.6](https://github.com/commercialhaskell/stack/releases/tag/v2.7.6)
 
 Default: Disabled
 

doc/azure_ci.md

@@ -39,11 +39,14 @@ We provide two fully baked configuration ready to be used on your projects:
   - [azure-windows-template.yml](https://raw.githubusercontent.com/commercialhaskell/stack/stable/doc/azure/azure-windows-template.yml)
     : Template for Azure Windows build
 
-  __NOTE__: It is likely going to be necessary to modify this configuration to
-  match the needs of your project, such as tweaking the build matrix to alter
-  which GHC versions you test against, or to specify GHC-version-specific
-  `stack.yaml` files if necessary. Don't be surprised if it doesn't work the
-  first time around. See the multiple GHC section below for more information.
+  !!! note
+
+      It is likely going to be necessary to modify this configuration to match
+      the needs of your project, such as tweaking the build matrix to alter
+      which GHC versions you test against, or to specify GHC-version-specific
+      `stack.yaml` files if necessary. Don't be surprised if it doesn't work the
+      first time around. See the multiple GHC section below for more
+      information.
 
 ## Creating Azure Pipelines
 

doc/faq.md

@@ -250,9 +250,11 @@ Stack will automatically install build tools required by your packages or their
 dependencies, in particular [Alex](https://hackage.haskell.org/package/alex) and
 [Happy](https://hackage.haskell.org/package/happy).
 
-__NOTE__: This works when using LTS or nightly resolvers, not with GHC or
-custom resolvers. You can manually install build tools by running, e.g.,
-`stack build alex happy`.
+!!! note
+
+    This works when using LTS or nightly resolvers, not with GHC or custom
+    resolvers. You can manually install build tools by running, e.g.,
+    `stack build alex happy`.
 
 ## How does Stack choose which snapshot to use when creating a new configuration file?
 

doc/maintainers/haskellstack.org.md

@@ -111,6 +111,30 @@ markdown_extensions:
 - pymdownx.superfences
 ~~~
 
+Other extensions to the basic Markdown syntax used include:
+
+* Admonitions
+
+    !!! info
+
+        This is an example of an 'info' admonition.
+
+* Content tabs, which can be nested
+
+    !!! info
+
+        Content tabs are used so that users of different operating systems, or
+        different distributions of Linux, can be presented with content specific
+        to their needs.
+
+* icons and emojis
+
+    !!! info
+
+        The `octicons-tag-24` icon (:octicons-tag-24:) is used to refer to
+        versions of Stack. The `material-cloud-download-outline` icon
+        (:material-cloud-download-outline:) is used to signify a download link.
+
 ## Testing
 
 Online documentation can be tested by establishing a branch on the respository

doc/maintainers/team_process.md

@@ -84,7 +84,7 @@ etc) that amounts to about one or two hours spent per week being on-call.
 Again, these estimates will evolve over time as we settle into an optimal
 process, but for now we anticipate growing the team to about eight members
 (which is the size of the `Stackage` team as well), each of whom is likely to
-spend about two hours in total on upkeep work every eight weeks. 
+spend about two hours in total on upkeep work every eight weeks.
 
 
 ## Issue and pull request interaction guidelines
@@ -138,7 +138,7 @@ question. If you're not sure who's best to consult you should ask on
 
 Try to be clear to the requester that you're opening the discussion up to more
 participants and that the proposal will require thoughtful consideration
-(probably a majority vote) before any decision is made. 
+(probably a majority vote) before any decision is made.
 
 Also remember that busy schedules, lack of complete familiarity with a given
 subject, strong-yet-opposing opinions held by equally rational people, and many
@@ -150,7 +150,7 @@ on-track and concrete.
 respectful "no".*
 
 *If feasible, propose alternative solutions or educate the user in preference to
-complicating `Stack` or accepting scope-creep.* 
+complicating `Stack` or accepting scope-creep.*
 
 With respect to assessing a PR's code, @snoyberg has outlined some
 [tips for successfully getting one's work merged
@@ -205,11 +205,13 @@ When closing an issue, please provide a brief explanation for why the issue was
 closed, such as a reference to a PR, a comment about lack of clarification,
 etc.
 
-__NOTE__ The following sections establish rules under which a bug report will
-be closed by the maintainer team. The goal is to avoid a situation where issues
-linger in an indeterminate state. The maintainer team is allowed to disregard
-these "rules" at any point. In other words: the goal isn't to allow people to
-"lawyer" issues.
+!!! note
+
+    The following sections establish rules under which a bug report will be
+    closed by the maintainer team. The goal is to avoid a situation where issues
+    linger in an indeterminate state. The maintainer team is allowed to
+    disregard these "rules" at any point. In other words: the goal isn't to
+    allow people to "lawyer" issues.
 
 ### Discussion
 

doc/nix_integration.md

@@ -2,7 +2,7 @@
 
 # Nix integration
 
-(since 0.1.10.0)
+[:octicons-tag-24: 0.1.10.0](https://github.com/commercialhaskell/stack/releases/tag/v0.1.10.0)
 
 [Nix](https://nixos.org/) is a purely functional package manager. Stack can be
 configured to integrate with Nix.

doc/travis_ci.md

@@ -18,11 +18,13 @@ ready to be used on your projects:
   and macOS. The configuration is significantly more involved to allow
   for all of this branching behavior.
 
-  __NOTE__: It is likely going to be necessary to modify this configuration to
-  match the needs of your project, such as tweaking the build matrix to alter
-  which GHC versions you test against, or to specify GHC-version-specific
-  `stack.yaml` files if necessary. Don't be surprised if it doesn't work the
-  first time around. See the multiple GHC section below for more information.
+    !!! note
+        It is likely going to be necessary to modify this configuration to match
+        the needs of your project, such as tweaking the build matrix to alter
+        which GHC versions you test against, or to specify GHC-version-specific
+        `stack.yaml` files if necessary. Don't be surprised if it doesn't work
+        the first time around. See the multiple GHC section below for more
+        information.
 
 Each of these configurations is ready to be used immediately, just
 copy-paste the content into the `.travis.yml` file in the root or your