Merge branch 'master' into lint-md

1 files changed, 34 insertions, 18 deletions

diff --git a/themes/docsy/README.md b/themes/docsy/README.md
index f61eff67c..89dde4e5c 100644
--- a/themes/docsy/README.md
+++ b/themes/docsy/README.md
@@ -1,34 +1,50 @@
 # Docsy
 
-Docsy is a Hugo theme for technical documentation sets, providing simple navigation, site structure, and more.
+Docsy is a [Hugo](https://gohugo.io/) theme for technical documentation sets, providing simple navigation, site structure, and more.
 
-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://testydocsy.netlify.com/](https://testydocsy.netlify.com/), where you can find detailed theme instructions under **Documentation -> Getting Started**.
+This is not an officially supported Google product. This project is actively being maintained.
 
-To use the Docsy theme, you can either:
+## Prerequisites
 
-* Copy and edit the example site’s repo, which will also give you a skeleton structure for your top-level and documentation sections, or
-* 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.
+The following are basic prerequisites for using Docsy in your site:
 
-This is not an officially supported Google product. This project is currently maintained.
+- 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), make sure you download the `_extended` version 
+  which supports SCSS.
 
-## Installation and prerequisites
+- 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:
 
-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.
+  ```
+  sudo npm install -D --save autoprefixer
+  sudo npm install -D --save postcss-cli
+  ```
 
-If you want to do stylesheet changes, you will also need `PostCSS` to create the final assets. You can also install it locally with:
+## Example and usage
 
-```
-npm install
-````
+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://example.docsy.dev/](https://example.docsy.dev/).
+
+To use the Docsy theme for your own site:
+
+  - (Recommended) Copy the [example project](https://github.com/google/docsy-example),
+	   which includes the Docsy theme as a submodule.
+    You can customize this pre-configured basic site into your own Docsy themed site. 
+    [Learn more...](https://github.com/google/docsy-example)
+  
+  - Add Docsy to your existing Hugo site repo's `themes` directory. You can either add Docsy as a Git submodule, or 
+    clone the Docsy theme into your project.
 
-To use a local version of the theme files, clone the repo using:
+See the [Docsy Getting Started Guide](https://docsy.dev/docs/getting-started/) for 
+details about the various usage options.
+
+## Documentation
+
+Docsy has its own user guide (using Docsy, of course!) with lots more information about using the theme, which you can find at [https://docsy.dev/](https://docsy.dev/). Alternatively you can use Hugo to generate and serve a local copy of the guide (also useful for testing local theme changes), making sure you have installed all the prerequisites listed above:
 
 ```
 git clone --recurse-submodules --depth 1 https://github.com/google/docsy.git
+cd docsy/userguide/
+hugo server --themesDir ../..
 ```
 
-## Theme documentation
-
-Detailed documentation for this theme is in the Docsy Example Project under **Documentation -> Getting Started**.
-The Docsy Example Project is on [GitHub](https://github.com/google/docsy-example) and is hosted at [https://testydocsy.netlify.com/](https://testydocsy.netlify.com/).
+Note that you need the `themesDir` flag when running Hugo because the site files are inside the theme repo.