User guide: adding instructions on how to use and update docsy as hug…

…o module

userguide/content/en/docs/Theme installation/Docsy-As-Module/_index.md

@@ -0,0 +1,12 @@
+---
+title: "Option 1: Making use of Docsy Theme as Hugo Module (Modern)"
+linkTitle: "Docsy as Hugo Module"
+weight: 1
+date: 2021-12-08T10:33:16+01:00
+description: >
+  Instructions on modern installation of the Docsy theme as hugo module which is automatically pulled in.
+---
+
+### Two Routes To Built Your Site
+
+You have to choose between two different routes procedure when building your site. As beginner, you are advised to choose the first route. Experts will choose the second route which gives you maximum flexibility at the cost of higher implementation effort.

userguide/content/en/docs/Theme installation/Docsy-As-Module/example-site-as-template.md

@@ -0,0 +1,81 @@
+---
+title: "Route 1: Start with a clone of the prepopulated Docsy example site (for beginners)"
+linkTitle: "Start with a prepopulated site"
+date: 2021-12-08T09:21:54+01:00
+weight: 2
+description: >
+  Start off with your new hugo site using a clone of the prepopulated Docsy example site theme as starting point.
+---
+
+As beginner, it is recommended that you use the sources of the [Docsy example site](https://github.com/google/docsy-example) as starting point of your new site. This approach gives you a skeleton structure for your site, with top-level and documentation sections and templates that you can modify as necessary. The example site automatically pulls in the Docsy theme as a [Hugo module](https://gohugo.io/hugo-modules/), so it's easy to [keep up to date](/docs/updating/updating-hugo-module/).
+
+## TL;DR: Setup for the impatient expert
+
+At your Unix shell or your Windows command line, issue:
+
+```
+git clone https://github.com/google/docsy.git my-new-site
+cd  my-new-site
+hugo server
+```
+
+You now can preview your new site inside your browser at [http://localhost:1313](http://localhost:1313/).
+
+## Detailed Setup instructions
+
+### Clone the Docsy example site
+
+The [Example Site](https://example.docsy.dev) gives you a good starting point for building your docs site and is
+pre-configured to automatically pull in the Docsy theme as Hugo module.
+There are two different routes to get a local clone of the Example Site:
+If you want to create a local site repo only, choose route 1.
+If you do have a GitHub account and additionally want to create a remote GitHub repo associated with your local site repo go for route 2.
+
+*  [Route 1: Using the command line (local site repo only)](#using-the-command-line)
+*  [Route 2: Using the GitHub UI (local site repo + associated remote GitHub repo)](#using-the-github-ui) 
+
+#### Route 1: Using the command line (local site repo only)
+
+If you want  to use a remote repository different from GitHub (e.g. [GitLab](https://gitlab.com), [BitBucket](https://bitbucket.org/), [AWS CodeCommit](https://aws.amazon.com/codecommit/), [Gitea](https://gitea.io/) or alike) or if you don't want a remote rpo at all, simply make a local working copy of the example site directly using `git clone`. As last parameter, give your local repo name (here: `my-new-site`):
+
+```
+git clone https://github.com/google/docsy-example.git my-new-site
+```
+
+#### Route 2: Using the GitHub UI (local site repo + associated remote GitHub repo)
+
+As the Docsy example site repo is a [template repository](https://github.blog/2019-06-06-generate-new-repositories-with-repository-templates/), creating your own remote GitHub clone of this Docsy example site repo is quite easy:
+
+1. Go to the [Docsy example site repo](https://github.com/google/docsy-example) and click **Use this template**.
+
+1. Chose a name for your new repository (e.g. `my-new-site`) and type it in the **Repository name** field. You can also add an optional **Description**.
+
+1. Click **Create repository from template** to create your new repository. Congratulations, you justed created your remote Github clone which now serves as starting point for your own site!
+
+1. Make a local copy of your newly created GitHub repository, using git's `clone` subcommand, give your repo's web URL as last parameter.
+
+    <pre>
+    git clone <em>https://github.com/me-at-github/my-new-site.git</em>
+    </pre>
+
+Now you can make local edits and test your copied site locally with Hugo.
+
+### Preview your site
+
+To build and preview your site locally, switch to the root of your cloned project and use hugos's `server` subcommand::
+
+```
+cd my-new-site
+hugo server
+```
+
+Preview your site in your browser at: [http://localhost:1313](http://localhost:1313/).
+Thanks to Hugo's live preview, you can immediately see the effect of changes that you are making to the source files of your local repo.
+Use `Ctrl + c` to stop the Hugo server whenever you like.
+[See the known issues on MacOS](/docs/getting-started/known_issues/#macos).
+
+## What's next?
+
+* [Edit existing content and add more pages](/docs/adding-content/)
+* [Customize your site](/docs/adding-content/lookandfeel/)
+* [Publish your site](/docs/deployment/).

userguide/content/en/docs/Theme installation/Docsy-As-Module/installation-prerequisites.md

@@ -0,0 +1,110 @@
+---
+title: "Pre-Installation of Prerequisites"
+linkTitle: "Installation of Prerequisites"
+date: 2021-12-08T11:12:59+01:00
+weight: 1
+description: >
+  Prerequisites needed prior to setup of a hugo site with Docsy theme (as hugo module).
+---
+
+## Prerequisites and installation
+
+### Install Hugo 
+
+You need a [recent **extended** version](https://github.com/gohugoio/hugo/releases) (we recommend version 0.75.0 or later) of [Hugo](https://gohugo.io/) to do local builds and previews of sites (like this one) that use Docsy. If you install from the release page, make sure to get the `extended` Hugo version, which supports [SCSS](https://sass-lang.com/documentation/file.SCSS_FOR_SASS_USERS.html); you may need to scroll down the list of releases to see it. 
+
+For comprehensive Hugo documentation, see [gohugo.io](https://gohugo.io/).
+
+#### Linux
+
+Be careful using `sudo apt-get install hugo`, as it [doesn't get you the `extended` version for all Debian/Ubuntu versions](https://gohugo.io/getting-started/installing/#debian-and-ubuntu), and may not be up-to-date with the most recent Hugo version.
+
+If you've already installed Hugo, check your version:
+
+```
+hugo version
+```
+If the result is `v0.75` or earlier, or if you don't see `Extended`, you'll need to install the latest version. You can see a complete list of Linux installation options in [Install Hugo](https://gohugo.io/getting-started/installing/#linux). The following shows you how to install Hugo from the release page:
+
+1.  Go to the [Hugo releases](https://github.com/gohugoio/hugo/releases) page.
+2.  In the most recent release, scroll down until you find a list of
+    **Extended** versions.
+3.  Download the latest extended version (`hugo_extended_0.9X_Linux-64bit.tar.gz`).
+4.  Create a new directory:
+
+        mkdir hugo
+
+5.  Extract the files you downloaded to `hugo`.
+
+6.  Switch to your new directory:
+
+        cd hugo
+
+7.  Install Hugo:
+
+        sudo install hugo /usr/bin
+
+#### macOS
+
+Install Hugo using [Brew](https://gohugo.io/getting-started/installing/#homebrew-macos).
+
+#### As an `npm` module
+
+You can install Hugo as an `npm` module using [`hugo-bin`](https://www.npmjs.com/package/hugo-bin). This adds `hugo-bin` to your `node_modules` folder and adds the dependency to your `package.json` file.  To install the extended version of Hugo:
+
+```
+npm install hugo-extended --save-dev
+```
+
+See the [`hugo-bin` documentation](https://www.npmjs.com/package/hugo-bin) for usage details.
+
+### Install Go language
+
+Hugo's commands for module management require that the Go programming language is installed on your system. Check whether `go` is already present in your system:
+
+```
+$ go version
+go version go1.17.5 windows/amd64
+```
+
+If `go` language is not installed on your system yet, head over to the [download area](https://go.dev/dl/) of the Go website, choose the installer for your system architecture and execute it. Afterwards, check for a successful installation.
+
+{{% alert title="Warning" color="warning" %}}
+Make sure you are using go version 1.12 or higher, otherwise you night run in trouble.
+{{% /alert %}}
+
+### Install Git VCS client
+
+Hugo's commands for module management require that the git client is installed on your system. Check whether `git` is already present in your system:
+
+```
+git version
+git version 2.34.1.windows.1
+```
+
+If no `git` client is installed on your system yet, head over to the [Git website](https://git-scm.com/), download the installer for your system architecture and execute it. Afterwards, check for a successful installation.
+
+### Install PostCSS
+
+To build or update your site's CSS resources, you also need [`PostCSS`](https://postcss.org/) to create the final assets. If you need to install it, you must have a recent version of [NodeJS](https://nodejs.org/en/) installed on your machine so you can use `npm`, the Node package manager. By default `npm` installs tools under the directory where you run [`npm install`](https://docs.npmjs.com/cli/v6/commands/npm-install#description):
+
+```
+npm install -D autoprefixer
+npm install -D postcss-cli
+```
+
+Starting in [version 8 of `postcss-cli`](https://github.com/postcss/postcss-cli/blob/master/CHANGELOG.md), you must also separately install `postcss`:
+
+```
+npm install -D postcss
+```
+
+Note that versions of `PostCSS` later than 5.0.1 will not load `autoprefixer` if installed [globally](https://flaviocopes.com/npm-packages-local-global/), you must use a local install.
+
+## What's next?
+
+With all prerequisites installed, you now have to select how to start off with your new hugo site
+
+* [Start with a prepopulated site (for beginners)](/docs/getting-started/docsy-as-module/example-site-as-template/)
+* [Start site from scratch (for experts)](/docs/getting-started/docsy-as-module/start-from-scratch/)
+