Use annotations to Welcome! page

Author: mpilgrem

doc/README.md

@@ -205,39 +205,37 @@ Stack can be installed directly or by using the GHCup tool.
 
 ## Quick Start guide
 
-For an immediate experience of using Stack to build an executable with Haskell,
-first you need to follow the [guide to install Stack](#how-to-install-Stack).
+Once Stack is installed, you can get an immediate experience of using it to
+build an executable with Haskell.
 
 ### Step 1: Start your new project
 
 A complex project can have more than one package and each package can have more
 than one executable (program). However, to start a new single-package project
-named `my-project`, issue these four commands in a terminal:
-
-1.  `stack new my-project`
-
-    This command will create a new directory, named `my-project`. It contains
-    all the files needed to start a project correctly, using a default template.
-
-2.  `cd my-project`
+named `my-project`, issue these four commands in a terminal (click
+:material-plus-circle: to learn more about each command):
+
+~~~shell
+stack new my-project # (1)!
+cd my-project # (2)!
+stack build # (3)!
+stack exec my-project-exe # (4)!
+~~~
 
-    This command will change the current working directory to that directory.
+1.  Create a new directory named `my-project`. It contains all the files needed
+    to start a project correctly, using a default template.
 
-3.  `stack build`
+2.  Change the current working directory to `my-project`.
 
-    This command will build the template project and create an executable named
-    `my-project-exe` (on Windows, `my-project-exe.exe`).
+3.  Build the template project and create an executable named `my-project-exe`.
 
     First, if necessary, Stack will download a version of GHC in an isolated
     location. That won't interfere with other GHC installations on your system.
     (On Windows, if necessary, Stack will also download
     [MSYS2](https://www.msys2.org/). MSYS2 is a project that provides popular
-    tools for developers on Windows).
+    tools for developers on Windows.)
 
-4.  `stack exec my-project-exe`
-
-    This command will run (execute) the built executable, in Stack's
-    environment.
+4.  Run (execute) the built executable, in Stack's environment.
 
 For a complete list of Stack's commands, and flags and options common to those
 commands, simply command:
@@ -255,13 +253,11 @@ stack build --help
 
 If you want to launch a run-eval-print loop (REPL) environment, then command:
 
-~~~text
-stack repl
+~~~shell
+stack repl # (1)!
 ~~~
 
-!!! info
-
-    `stack ghci` can be used instead of `stack repl`. GHCi is GHC's REPL tool.
+1.  `stack ghci` can be used instead of `stack repl`. GHCi is GHC's REPL tool.
 
 People organise Haskell code into packages. If you want to use Stack to install
 an executable provided by a Haskell package, then all you have to do is command:
@@ -273,60 +269,72 @@ stack install <package-name>
 ### Step 2: Next steps
 
 The `stack new my-project` command in step one should have created the following
-files and directories (among others):
+files and directories, among others. Click :material-plus-circle: to learn more
+about each file:
 
-~~~text
+~~~shell
 .
 ├── app
-│   └── Main.hs
+│   └── Main.hs # (1)!
 ├── src
-│   └── Lib.hs
+│   └── Lib.hs # (2)!
 ├── test
-│   └── Spec.hs
-├── my-project.cabal
-├── package.yaml
-└── stack.yaml
+│   └── Spec.hs # (3)!
+├── my-project.cabal # (4)!
+├── package.yaml # (5)!
+└── stack.yaml # (6)!
 ~~~
 
-The Haskell source code for the executable (application) is in file `Main.hs`.
+1.  The Haskell source code for the executable (application).
+
+    As your project develops you can add further source code files to the `app`
+    directory.
+
+2.  The executable uses a library. The Haskell source code for the library.
 
-The executable uses a library. Its source code is in file `Lib.hs`.
+    As your project develops you can add further source code files to the `src`
+    directory.
 
-The contents of `my-project.cabal` describes the project's package. That file is
-generated by the contents of `package.yaml`.
+3.  The package has a test suite executable. The Haskell source code for the
+    test suite.
 
-!!! info
+    As your project develops you can add further source code files to the `test`
+    directory.
 
-    If you want, you can delete the `package.yaml` file and update the
-    `my-project.cabal` file directly. Stack will then use that file.
+4.  A file describing the package in the Cabal format, including other packages
+    on which depends. Stack generates it from the contents of the `package.yaml`
+    file.
 
-The contents of `stack.yaml` describe Stack's own project-level configuration.
+    If the `package.yaml` file is deleted, Stack will use the Cabal file.
 
-You can edit the source files in the `src` directory (used for the library) or
-the `app` directory (used for the executable (application)).
+5.  A file describing the package in the Hpack format. Stack generates the
+    `my-project.cabal` file from its contents.
 
-As your project develops, you may need to depend on a library provided by
-another Haskell package. If you do, then add the name of that new package to the
-file `package.yaml`, in its `dependencies:` section.
+    If you want, you can delete the file and update the Cabal file directly.
 
-!!! info
+    As your project develops, you may need to depend on a library provided by
+    another Haskell package. If you do, add the name of that new package to
+    the `dependencies:` section.
 
-    When you use `stack build` again, Stack will use `package.yaml` to create an
-    updated `my-project.cabal` for you.
+6.  Stack's project-level configuration. This specifies a snapshot that, in
+    turn, specifies a version of GHC and a set of package versions chosen to
+    work well together. It also identifies the local packages in the project.
 
-If Stack reports that the Stack configuration has no specified version for the
-new package, then follow Stack's likely recommended action to add a specific
-version of that package your project's `stack.yaml` file, in its `extra-deps:`
-section.
+    If you add a new package as a dependency in the package description, and
+    Stack reports that the Stack configuration has no specified version for it,
+    then follow Stack's likely recommended action to add a specific version to
+    the `extra-deps:` section.
 
 That was a really fast introduction on how to start to code in Haskell using
-Stack. If you want to go further, we highly recommend you read Stack's
-introductory [user's guide](tutorial/index.md).
+Stack. If you want to go further, we recommend you read Stack's guide to
+[getting started](tutorial/index.md).
 
 ## Complete guide to Stack
 
-A complete [user's guide](tutorial/index.md) to Stack is available, covering all
-of the most common ways to use Stack. Terms used in Stack's documentation are
+A complete guide to Stack is available, covering the most common ways to
+[use Stack](tutorial/index.md), its [commands](commands/index.md), its
+[configuration](configure/index.md), specific [topics](topics/index.md), and
+[frequently asked questions](faq.md). Terms used in Stack's documentation are
 also explained in the [glossary](glossary.md).
 
 ## Why Stack?
@@ -338,38 +346,58 @@ experienced developers need.
 
 Stack does not stand alone. It is built on the great work provided by:
 
-*   The __Glasgow Haskell Compiler__ ([GHC](https://www.haskell.org/ghc/)), the
-    premier Haskell compiler. Stack will manage your GHC installations and
-    automatically select the appropriate version of GHC for your project.
-*   The __Cabal build system__. Cabal is a specification for defining Haskell
-    packages and a [library](https://hackage.haskell.org/package/Cabal) for
-    performing builds.
+<div class="grid cards" markdown>
+
+-   :fontawesome-solid-gears:{ .lg .middle } __Glasgow Haskell Compiler__
+
+    The premier Haskell compiler. Stack will manage your GHC
+    installations and automatically select the appropriate version of GHC for
+    your project.
+
+    ---
 
-    !!! info
+    [:octicons-arrow-right-24: Learn more](https://www.haskell.org/ghc/)
 
-        Cabal is also the name of another tool used for building Haskell code,
+-   :fontawesome-solid-trowel-bricks:{ .lg .middle } __Cabal build system__
+
+    A specification for defining Haskell packages and a library for performing
+    builds.[^1]
+
+    [^1]:
+        Cabal is also the name of a tool used for building Haskell code,
         provided by the `cabal-install` package. This guide distinguishes
         between them by Cabal (the library) and Cabal (the tool).
 
-* The __Hackage Haskell Package Repository__, a
-  [repository](https://hackage.haskell.org/) of Haskell packages providing
-  thousands of open source libraries and applications to help you get your work
-  done.
-* The __Stackage package collection__, sets of packages from Hackage that are
-  [curated](https://www.stackage.org/). That is, they are regularly tested for
-  compatibility. Stack defaults to using Stackage package sets to avoid
-  problems with incompatible dependencies.
+    ---
+
+    [:octicons-arrow-right-24: Learn more](https://hackage.haskell.org/package/Cabal)
+
+-   :octicons-database-24:{ .lg .middle } __Hackage__
+
+    A repository of Haskell packages providing thousands of open source
+    libraries and applications to help you get your work done.
+
+    ---
+
+    [:octicons-arrow-right-24: Learn more](https://hackage.haskell.org/)
+
+-   :fontawesome-solid-cubes-stacked:{ .lg .middle } __Stackage__
+
+    Sets of packages from Hackage that are chosen to work well together and
+    with a specific version of GHC.
+
+    ---
+
+    [:octicons-arrow-right-24: Learn more](https://www.stackage.org/)
+
+</div>
 
 Stack is provided by a team of volunteers and companies under the auspices of
 the [Commercial Haskell](http://commercialhaskell.com/) group. The project was
 originally spearheaded by [FP Complete](https://www.fpcomplete.com/) to answer
 the needs of commercial Haskell users. It has since become a thriving open
 source project meeting the needs of Haskell users of all types.
 
-If you'd like to get involved with Stack, check out the
-[newcomer friendly](https://github.com/commercialhaskell/stack/issues?q=is%3Aopen+is%3Aissue+label%3a%22newcomer+friendly%22)
-label on the GitHub issue tracker.
-
 ## Questions?
 
 For answers to frequently asked questions about Stack, please see the

mkdocs.yml

@@ -14,6 +14,7 @@ theme:
   icon:
     logo: material/language-haskell
   features:
+  - content.code.annotate
   - content.code.copy
   - content.code.select
   - content.tabs.link