Update prereqs and install in README

- (spell out postcss and autoprefixer) in order to run just `npm install`, the packages.json must exist (ie need to clone Docsy-example).
- clarify what the options are to "use Docsy" (submodule vs clone)

1 files changed, 38 insertions, 11 deletions

diff --git a/README.md b/README.md
index 7cbde72..6bf7d03 100644
--- a/README.md
+++ b/README.md
@@ -2,28 +2,52 @@
 
 Docsy is a [Hugo](https://gohugo.io/) theme for technical documentation sets, providing simple navigation, site structure, and more.
 
-This is not an officially supported Google product. This project is currently maintained.
+This is not an officially supported Google product. This project is actively being maintained.
 
 
-## Installation and prerequisites
+## Prerequisites and installation overview
 
-You need a recent version of Hugo to build sites using this theme (preferably 0.45+). If you install from the [release page](https://github.com/gohugoio/hugo/releases), make sure to get the `extended` Hugo version which supports SCSS. Alternatively, on macOS you can install Hugo via Brew.
+The following high-level list includes the basic prerequisites for using Docsy in your site. 
 
-You'll also need `PostCSS` to create the final CSS assets when building your site. You can install it locally with:
+<!-- TODO: Update to docsy.dev URL -->
+See the 
+[Docsy Getting Started Guide](https://docsydocs.netlify.com/docs/getting-started/) for a complete list of the
+prerequisites and details about the various installation options.
 
-```
-npm install
-````
+To use the Docsy theme in your site, you must meet the following prerequisites:
 
-To use a local version of the theme files, clone the repo using:
+- Install a recent release of the Hugo "extended" version (we recommend version 0.53 or later). If you install from the 
+  [release page](https://github.com/gohugoio/hugo/releases), you must ensure to download the `hugo_extended` version 
+  which supports SCSS.
 
-```
-git clone --recurse-submodules --depth 1 https://github.com/google/docsy.git
-```
+- Get the Docsy theme:
 
+  - (Recommended) Start with the Docsy Example project and use Docsy as a submodule. If you clone the Docsy Example site, 
+    you can modify and customize a pre-configured site, into your own Docsy themed site. 
+    [Learn more...](https://github.com/google/docsy-example)
+  
+  - Add docsy to your exsiting site. You can either add Docsy as a submodule, or clone the Docsy repo into your site.
+    See the complete list of [Docsy installation options](https://docsydocs.netlify.com/docs/getting-started/) .
+  
+    For example, to clone Docsy into the `theme` directory of your project, you run the following command from 
+    your project's root directory:
+    
+    ```
+    git clone --recurse-submodules --depth 1 https://github.com/google/docsy.git themes/docsy
+    ```
+
+- Install `PostCSS` so that the site build can create the final CSS assets. You can install it locally by running 
+  the following commands from the root directory of your project:
+
+  ```
+  sudo npm install -D --save autoprefixer
+  sudo npm install -D --save postcss-cli
+  ```
 
 ## Usage and documentation
 
+
+<!-- TODO: Update to docsy.dev URL -->
 You can find an example project that uses Docsy in the [Docsy Example Project repo](https://github.com/google/docsy-example). The Docsy Example Project is hosted at [https://goldydocs.netlify.com/](https://goldydocs.netlify.com/).
 
 To use the Docsy theme, you can either:
@@ -32,6 +56,8 @@ To use the Docsy theme, you can either:
 * Specify the Docsy theme like any other [Hugo theme](https://gohugo.io/themes/installing-and-using-themes/)
  when creating or updating your site. This gives you all the theme-y goodness but you’ll need to specify your own site structure.
 
+
+<!-- TODO: Update to docsy.dev URL -->
 Docsy also has its own user guide (using Docsy, of course!), which you can find at [https://docsydocs.netlify.com/](https://docsydocs.netlify.com/). Alternatively you can use Hugo to generate and serve a local copy (also useful for testing local theme changes), making sure you have installed all the prerequisites listed below:
 
 ```
@@ -42,5 +68,6 @@ hugo server --themesDir ../..
 
 Note that you need the `themesDir` flag because the site files are inside the theme repo.
 
+<!-- TODO: Update to docsy.dev URL -->
 You can find out much more about using Docsy in the [user guide](https://docsydocs.netlify.com/).