diff --git a/netlify.toml b/netlify.toml
index 0f24ebcc06..7ae15440ec 100644
--- a/netlify.toml
+++ b/netlify.toml
@@ -6,7 +6,7 @@ publish = "userguide/public"
 command = "npm run docs-install && npm run build:preview"
 
 [build.environment]
-GO_VERSION = "1.17.7"
+GO_VERSION = "1.18"
 HUGO_THEME = "repo"
 
 [context.production]
diff --git a/package.json b/package.json
index f0e8740ed3..17c6d23c09 100644
--- a/package.json
+++ b/package.json
@@ -17,6 +17,6 @@
     "bootstrap": "^4.6.1"
   },
   "devDependencies": {
-    "hugo-extended": "0.93.2"
+    "hugo-extended": "0.96.0"
   }
 }
diff --git a/userguide/config.toml b/userguide/config.toml
index cf463897ca..516b638437 100644
--- a/userguide/config.toml
+++ b/userguide/config.toml
@@ -132,7 +132,7 @@ prism_syntax_highlighting = false
 # User interface configuration
 [params.ui]
 # Enable to show the side bar menu in its compact state.
-sidebar_menu_compact = false
+sidebar_menu_compact = true
 sidebar_menu_foldable = false
 sidebar_cache_limit = 10
 # Set to true to disable breadcrumb navigation.
diff --git a/userguide/content/en/docs/Adding content/Shortcodes/index.md b/userguide/content/en/docs/Adding content/Shortcodes/index.md
index 5daec60bf1..3526aa5d7a 100644
--- a/userguide/content/en/docs/Adding content/Shortcodes/index.md	
+++ b/userguide/content/en/docs/Adding content/Shortcodes/index.md	
@@ -361,7 +361,7 @@ Karibu sana!
 
 Tabbed panes are implemented using two shortcodes:
 
-* The `tabpane` shortcode, which is the container element for the tabs. This shortcode can optionally held the named parameters `lang` and/or `highlight`. The values of these optional parameters are passed on as second `LANG` and third `OPTIONS` arguments to Hugo's built-in [`highlight`](https://gohugo.io/functions/highlight/) function which is used to render the code blocks of the individual tabs. In case the header text of the tab equals the `language` used in the tab's code block (as in the first tabbed pane example above), you may specify `langEqualsHeader=true` in the surrounding `tabpane` shortcode. Then, the header text of the individual tab is automatically set as `language` parameter of the respective tab.
+* The `tabpane` shortcode, which is the container element for the tabs. This shortcode can optionally hold the named parameters `lang` and/or `highlight`. The values of these optional parameters are passed on as second `LANG` and third `OPTIONS` arguments to Hugo's built-in [`highlight`](https://gohugo.io/functions/highlight/) function which is used to render the code blocks of the individual tabs. In case the header text of the tab equals the `language` used in the tab's code block (as in the first tabbed pane example above), you may specify `langEqualsHeader=true` in the surrounding `tabpane` shortcode. Then, the header text of the individual tab is automatically set as `language` parameter of the respective tab.
 * The various `tab` shortcodes which actually represent the tabs you would like to show. We recommend specifying the named parameter `header` for each text in order to set the header text of each tab. If needed, you can additionally specify the named parameters `lang` and `highlight` for each tab. This allows you to overwrite the settings given in the parent `tabpane` shortcode. If the language is neither specified in the `tabpane` nor in the `tab`shortcode, it defaults to Hugo's site variable `.Site.Language.Lang`.
 
 ## Card panes
@@ -386,7 +386,7 @@ When authoring content, it's sometimes very useful to put similar text blocks or
 Docsy supports creating such card panes via different shortcodes:
 
 * The `cardpane` shortcode which is the container element for the various cards to be presented.
-* The `card` shortcodes, with each shortcode representing an individual card. While cards are often presented inside a card group, a single card may stand on its own, too. A `card` shortcode can held text, images or any other arbitrary kind of markdown or HTML markup as content. If your content is programming code, you are advised to make use of the `card-code` shortcode, a special kind of card with code-highlighting and other optional features like line numbers, highlighting of certain lines, ….
+* The `card` shortcodes, with each shortcode representing an individual card. While cards are often presented inside a card group, a single card may stand on its own, too. A `card` shortcode can hold text, images or any other arbitrary kind of markdown or HTML markup as content. If your content is programming code, you are advised to make use of the `card-code` shortcode, a special kind of card with code-highlighting and other optional features like line numbers, highlighting of certain lines, ….
 
 ### Shortcode `card` (for text, images, …)
 
@@ -459,7 +459,7 @@ int main(void)
 }
 {{< /card-code >}}
 
-<br/>The `card-code` shortcode can optionally held the named parameters `lang` and/or `highlight`. The values of these optional parameters are passed on as second `LANG` and third `OPTIONS` arguments to Hugo's built-in [`highlight`](https://gohugo.io/functions/highlight/) function which is used to render the code block presented on the card.
+<br/>The `card-code` shortcode can optionally hold the named parameters `lang` and/or `highlight`. The values of these optional parameters are passed on as second `LANG` and third `OPTIONS` arguments to Hugo's built-in [`highlight`](https://gohugo.io/functions/highlight/) function which is used to render the code block presented on the card.
 
 ### Card groups
 
diff --git a/userguide/content/en/docs/Deployment/_index.md b/userguide/content/en/docs/Deployment/_index.md
index 35a2e91029..2fc52c1277 100644
--- a/userguide/content/en/docs/Deployment/_index.md
+++ b/userguide/content/en/docs/Deployment/_index.md
@@ -56,7 +56,7 @@ Then follow the instructions in [Host on Netlify](https://gohugo.io/hosting-and-
    1. For your **Build command**, specify `cd themes/docsy && git submodule update -f --init && cd ../.. && hugo`. You need to specify this rather than just `hugo` so that Netlify can use the theme's submodules. If you don't want your site to be indexed by search engines, you can add an environment flag to specify a non-`production` environment, as described in [Build environments and indexing](#build-environments-and-indexing).
    1. Click **Show advanced**. 
    1. In the **Advanced build settings** section, click **New variable**. 
-   1. Specify `HUGO_VERSION` as the **Key** for the new variable, and `0.53` or later as its **Value**. 
+   1. Specify `HUGO_VERSION` as the **Key** for the new variable, and `0.73` or later as its **Value**. 
 1. Click **Deploy site**.
 
 {{% alert title="Note" color="primary" %}}
diff --git a/userguide/content/en/docs/Getting started/_index.md b/userguide/content/en/docs/Getting started/_index.md
deleted file mode 100755
index 7ec116599a..0000000000
--- a/userguide/content/en/docs/Getting started/_index.md	
+++ /dev/null
@@ -1,330 +0,0 @@
-
----
-title: "Getting Started"
-linkTitle: "Getting Started"
-weight: 2
-date: 2018-07-30
-description: >
-  This page tells you how to get started with the Docsy theme, including installation and basic configuration.
----
-
-
-## Prerequisites and installation
-
-### Use our Docker image
-
-We provide a Docker image that you can use to run and test your Docsy site
-locally, without having to install all Docsy's dependencies.
-
-You can see how to get started with this approach by following our [Docker
-Quickstart tutorial](quickstart-docker). If you don't want to use Docker,
-follow the instructions below to install Hugo and PostCSS.
-
-### Install Hugo 
-
-You need a [recent **extended** version](https://github.com/gohugoio/hugo/releases) (must be version 0.77.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.77` 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 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.
-
-## Using the theme
-
-To use the Docsy Hugo theme, you have a couple of options:
-
-*   **Copy and edit the source for the [Docsy example site](https://github.com/google/docsy-example).** 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 uses Docsy as a [Git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules), so it's easy to [keep up to date](/docs/updating/).
-*   **Build your own site using the Docsy theme.** Specify the [Docsy theme](https://github.com/google/docsy) like any other [Hugo theme](https://gohugo.io/themes/) when creating or updating your site. With this option, you'll get Docsy look and feel, navigation, and other features, but you'll need to specify your own site structure. 
-
-### Option 1: Copy 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 use the Docsy theme as a Git submodule. You can copy the Example Site either by:
-
-*  [Using the GitHub UI](#using-the-github-ui)
-*  [Using the command line](#using-the-command-line)
-
-#### Using the GitHub UI
-
-This is the simplest approach, as the Docsy example site repo is a [template repository](https://github.blog/2019-06-06-generate-new-repositories-with-repository-templates/). To create your own copy of the Docsy example site repo:
-
-1. Go to the [repo page](https://github.com/google/docsy-example) and click **Use this template**.
-
-1. Type your chosen name for your new repository 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 now have a Docsy site repo!
-
-1. To test your copied site locally with Hugo, or make local edits, you'll also need to make a local copy of your new repository. To do this, use `git clone`, replacing `https://github.com/my/example.git` with your repo's web URL (don't forget to use `--recurse-submodules` or you won't pull down some of the code you need to generate a working site):
-
-    <pre>
-    git clone --recurse-submodules --depth 1 <em>https://github.com/my/example.git</em>
-    </pre>
-
-You can now edit your local versions of the site's source files. To preview your site, go to your site root directory and run `hugo server` ([see the known issues on MacOS](#known-issues)). By default, your site will be available at http://localhost:1313/. To push changes to your new repo, go to your site root directory and use `git push`.
-
-#### Using the command line
-
-To copy the example site:
-
-1.  Make a local working copy of the example site directly using `git clone`:
-
-        git clone https://github.com/google/docsy-example.git
-    
-1. Switch to the root of the cloned project, for example:
-
-        cd docsy-example
-
-1. Get local copies of the project submodules so you can build and run your site locally:
-
-        git submodule update --init --recursive
-    
-1. Build your site:
-    
-        hugo server
-    
-1. Preview your site in your browser at: http://localhost:1313/. You can use `Ctrl + c` to stop the Hugo server whenever you like.
-   [See the known issues on MacOS](#known-issues).
-
-1. Now that you have a site running, you can push it to a new repository:
-
-   1. [Create a new repository in GitHub](https://help.github.com/en/articles/create-a-repo) 
-      for your site with your chosen repo name. For clarity you may also want to rename the root 
-      directory (`docsy-example`) of your working copy to match, though everything will still 
-      work even if you don't.
-
-   1. Configure 
-      [`origin`](https://help.github.com/en/articles/configuring-a-remote-for-a-fork)
-      in your project. From your site's root directory, set the URL for `origin` to your new 
-      repo (otherwise you'll be trying to push changes to `google/docsy` rather than to your repo):
-
-            git remote set-url origin https://github.com/MY-SITE/EXAMPLE.git
-
-
-   1. Verify that your remote is configured correctly by running:
-      
-            git remote -v
- 
-	   
-   1. Push your Docsy site to your repository:
-
-            git push -u origin master
-
-### Option 2: Use the Docsy theme in your own site
-
-Specify the [Docsy theme](https://github.com/google/docsy) like any other Hugo theme when creating or updating your site. This gives you all the theme-y goodness but you'll need to specify your own site structure.  You can either use the theme as a submodule (our recommended approach for easy updates), or just clone the theme into your project's `themes` subdirectory.
-
-Whichever approach you use, for simplicity we recommend copying and editing our [example site configuration](#basic-site-configuration) for your project, or you may get Hugo errors for missing parameters and values when you try to build your site.
-
-#### Using the Docsy theme as a submodule
-
-Adding Docsy as a Git submodule is our recommended approach for using the theme, as it means your project
-always refers to the Docsy repo version at your chosen revision, rather than you having your own copy in 
-your repo that may result in merge conflicts when you try to update it. This is the approach used by our
-[example project](https://github.com/google/docsy-example).
-
-
-To create a new Hugo site project and then add the Docs theme as a submodule, run the following commands from your project's root directory. 
-
-```shell
-hugo new site myproject
-cd myproject
-git init
-git submodule add https://github.com/google/docsy.git themes/docsy
-echo 'theme = "docsy"' >> config.toml
-git submodule update --init --recursive
-```
-
-To add the Docsy theme to an existing site, run the following commands from your project's root directory:
-
-```
-git submodule add https://github.com/google/docsy.git themes/docsy
-echo 'theme = "docsy"' >> config.toml
-git submodule update --init --recursive
-```
-
-#### Cloning the Docsy theme to your project's `themes` subdirectory
-
-If you don't want to use a submodules (for example, if you want to customize and maintain your  own copy of the theme directly, or your deployment choice requires you to include a copy of the theme in your repository), you can clone the theme into your project.
-
-
-
-
-To clone Docsy into your project's `theme` folder, run the following commands from your project's root directory:
-
-```
-cd themes
-git clone https://github.com/google/docsy
-```
-
-If you want to build and/or serve your site [locally](/docs/deployment/#serving-your-site-locally), you also need to get local copies of the theme’s own submodules:
-
-```
-git submodule update --init --recursive
-```
-
-For more information, see [Theme Components](https://gohugo.io/hugo-modules/theme-components/) on the [Hugo](https://gohugo.io) site.
-
-#### Preview your site
-
-To build and preview your site locally:
-
-```
-cd myproject
-hugo server
-```
-    
-By default, your site will be available at http://localhost:1313/. [See the known issues on MacOS](#known-issues).
-
-## Basic site configuration
-
-Site-wide configuration details and parameters are defined in your project's `config.toml` file. These include your chosen Hugo theme (Docsy, of course!), project name, community links, Google Analytics configuration, and Markdown parser parameters. See the examples with comments in [`config.toml` in the example project](https://github.com/google/docsy-example/blob/master/config.toml) for how to add this information. **We recommend copying this `config.toml` and editing it even if you're just using the theme and not copying the entire Docsy example site**.
-
-The Docsy example site comes with some defaults you may want to remove or customize straight away:
-
-### Internationalization
-
-The Docsy example site supports content in English, Norwegian and Farsi. You can find out more about how Docsy supports multi-language content in [Multi-language support](/docs/language/).
-
-If you don't intend to translate your site, you can remove the language switcher by removing the following lines from `config.toml`:
-
-```
-[languages.no]
-title = "Docsy"
-description = "Docsy er operativsystem for skyen"
-languageName ="Norsk"
-contentDir = "content/no"
-time_format_default = "02.01.2006"
-time_format_blog = "02.01.2006"
-
-[languages.fa]
-title = "اسناد گلدی"
-description = "یک نمونه برای پوسته داکسی"
-languageName ="فارسی"
-contentDir = "content/fa"
-time_format_default = "2006.01.02"
-time_format_blog = "2006.01.02"
-```
-
-To remove the translated source files, delete both the `docsy-example/content/no` and the  `docsy-example/content/fa` directory.
-
-### Search
-
-By default, the Docsy example site uses its own [Google Custom Search Engine](https://cse.google.com/cse/all). To disable this site search, delete or comment out the following lines:
-
-```
-# Google Custom Search Engine ID. Remove or comment out to disable search.
-gcs_engine_id = "011737558837375720776:fsdu1nryfng"
-```
-
-To use your own Custom Search Engine, replace the value in the `gcs_engine_id` with the ID of your own search engine. Or [choose another search option](/docs/adding-content/navigation/#site-search-options).
-
-## Known issues
-
-### MacOS
-
-#### Errors: `too many open files` or `fatal error: pipe failed`
-
-By default, MacOS permits a small number of open File Descriptors. For larger sites, or when you're simultaneously running multiple applications,
-you might receive one of the following errors when you run [`hugo server`](https://gohugo.io/commands/hugo_server/) to preview your site locally:
-
-* POSTCSS v7 and earlier:
-
-  ```
-  ERROR 2020/04/14 12:37:16 Error: listen tcp 127.0.0.1:1313: socket: too many open files
-  ```
-* POSTCSS v8 and later:
-
-  ```
-  fatal error: pipe failed
-  ```
-
-##### Workaround
-
-To temporarily allow more open files:
-
-1. View your current settings by running:
-
-   ```
-   sudo launchctl limit maxfiles
-   ```
-
-2. Increase the limit to `65535` files by running the following commands. If your site has fewer files, you can set choose to set lower soft (`65535`) and 
-   hard (`200000`) limits. 
-   
-   ```shell
-   sudo launchctl limit maxfiles 65535 200000
-   ulimit -n 65535
-   sudo sysctl -w kern.maxfiles=200000
-   sudo sysctl -w kern.maxfilesperproc=65535
-   ```
-
-Note that you might need to set these limits for each new shell. 
-[Learn more about these limits and how to make them permanent](https://www.google.com/search?q=mac+os+launchctl+limit+maxfiles+site%3Aapple.stackexchange.com&oq=mac+os+launchctl+limit+maxfiles+site%3Aapple.stackexchange.com).
-
-### Windows Subsystem for Linux (WSL)
-
-If you're using WSL, ensure that you're running `hugo` on a Linux mount of the filesystem, rather than a Windows one, otherwise you may get unexpected errors.
-
-## What's next?
-
-* [Add content and customize your site](/docs/adding-content/)
-* Get some ideas from our [Example Site](https://github.com/google/docsy-example) and other [Examples](/docs/examples/).
-* [Publish your site](/docs/deployment/).
-
diff --git a/userguide/content/en/docs/Language/_index.md b/userguide/content/en/docs/Language/_index.md
index 6c522471af..9674ba6d3d 100644
--- a/userguide/content/en/docs/Language/_index.md
+++ b/userguide/content/en/docs/Language/_index.md
@@ -37,6 +37,10 @@ Any setting not defined in a `[languages]` block will fall back to the global va
 
 Once you've updated your site config, you create a content root directory for each language version in your source repo, such as  `content/en` for English text, and add your [content](/docs/adding-content/content/) as usual. See the [Hugo Docs](https://gohugo.io/content-management/multilingual) on multi-language support for more information.
 
+{{% alert title="Attention (only when using docsy as hugo module)" color="warning" %}}
+If you have a multi language installation, please make sure that the section `[languages]` inside your `config.toml` is declared before the section `[module]` with the module imports. Otherwise you will run into trouble!
+{{% /alert %}}
+
 {{% alert title="Tip" %}}
 If there's any possibility your site might be translated into other languages, consider creating your site with your content in a language-specific subdirectory, as it means you don't need to move it if you add another language.
 {{% /alert %}}
diff --git a/userguide/content/en/docs/Theme installation/Docsy-As-Module/_index.md b/userguide/content/en/docs/Theme installation/Docsy-As-Module/_index.md
new file mode 100644
index 0000000000..dc68918ca0
--- /dev/null
+++ b/userguide/content/en/docs/Theme installation/Docsy-As-Module/_index.md	
@@ -0,0 +1,21 @@
+---
+title: "Use Docsy as a Hugo Module"
+linkTitle: "Use Docsy as a Hugo Module"
+weight: 1
+date: 2021-12-08T10:33:16+01:00
+description: >
+  Learn how to get started with Docsy by using the theme as a Hugo Module.
+---
+
+[Hugo modules](https://gohugo.io/hugo-modules/) are the simplest and latest way to use Hugo themes like Docsy when building a website. Hugo uses the modules mechanism to pull in the theme files from the main Docsy repo at your chosen revision, and it’s easy to keep the theme up to date in your site. Our example site uses Docsy as a Hugo module.
+
+To find out about other setup approaches, see our [Get started](/docs/get-started/) overview. If you want to migrate an existing Docsy site to use Hugo Modules, see our [migration guide]().
+
+## Setup options with Hugo Modules
+
+To use Docsy as a Hugo Module, you have a couple of options:
+
+*   **Copy and edit the source for the [Docsy example site](https://github.com/google/docsy-example).** 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 uses Docsy as a Hugo Module.
+*   **Build your own site using the Docsy theme.** Specify the [Docsy theme](https://github.com/google/docsy) like any other [Hugo theme](https://gohugo.io/themes/) when creating or updating your site. With this option, you'll get Docsy look and feel, navigation, and other features, but you'll need to specify your own site structure. 
+
+If you're a beginner, we recommend that you get started by copying our example site. If you're already familiar with Hugo or want a very different site structure, you can follow our guide to start a site from scratch, which gives you maximum flexibility at the cost of higher implementation effort. In both cases you need to follow our prerequisites guide to make sure that you have installed Hugo and all necessary dependencies.
diff --git a/userguide/content/en/docs/Theme installation/Docsy-As-Module/example-site-as-template.md b/userguide/content/en/docs/Theme installation/Docsy-As-Module/example-site-as-template.md
new file mode 100644
index 0000000000..14fc56dc33
--- /dev/null
+++ b/userguide/content/en/docs/Theme installation/Docsy-As-Module/example-site-as-template.md	
@@ -0,0 +1,82 @@
+---
+title: "Create a new site: start with a prepopulated site"
+linkTitle: "Start with a prepopulated site"
+date: 2021-12-08T09:21:54+01:00
+weight: 2
+description: >
+  Create a new Hugo site by using a clone of the Docsy example site as your starting point.
+---
+
+The simplest way to create a new Docsy site is to use the source of the [Docsy example site](https://github.com/google/docsy-example) as starting point. 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/).
+
+If you prefer to create a site from scratch, follow the instructions in Start a site from scratch.
+
+## TL;DR: Setup for the impatient expert
+
+At your Unix shell or Windows command line, run the following command:
+
+```
+git clone -b sandbox https://github.com/google/docsy-example.git my-new-site
+cd  my-new-site
+hugo server
+```
+
+You now can preview your new site in 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 a Hugo Module.
+There are two different routes to get a local clone of the example site:
+
+* If you want to create a local copy only, choose option 1.
+* If you have a GitHub account and want to create a GitHub repo for your site go for option 2.
+
+#### Option 1: Using the command line (local copy only)
+
+If you want  to use a remote repository other than GitHub (such as [GitLab](https://gitlab.com), [BitBucket](https://bitbucket.org/), [AWS CodeCommit](https://aws.amazon.com/codecommit/), [Gitea](https://gitea.io/)) or if you don't want a remote repo at all, simply make a local working copy of the example site directly using `git clone`. As last parameter, give your chosen local repo name (here: `my-new-site`):
+
+```
+git clone -b sandbox https://github.com/google/docsy-example.git my-new-site
+```
+
+#### Option 2: Using the GitHub UI (local copy + associated 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/tree/sandbox) 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 just 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 by using `git clone`, giving 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 hugo's `server` command:
+
+```
+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?
+
+* Add some [basic configuration](/docs/theme-installation/basic-configuration/)
+* [Edit existing content and add more pages](/docs/adding-content/)
+* [Customize your site](/docs/adding-content/lookandfeel/)
+* [Publish your site](/docs/deployment/).
diff --git a/userguide/content/en/docs/Theme installation/Docsy-As-Module/installation-prerequisites.md b/userguide/content/en/docs/Theme installation/Docsy-As-Module/installation-prerequisites.md
new file mode 100644
index 0000000000..95b0708ca2
--- /dev/null
+++ b/userguide/content/en/docs/Theme installation/Docsy-As-Module/installation-prerequisites.md	
@@ -0,0 +1,109 @@
+---
+title: "Before you begin"
+linkTitle: "Before you begin"
+date: 2021-12-08T11:12:59+01:00
+weight: 1
+description: >
+  Prerequisites for building a site with Docsy as a Hugo Module.
+---
+
+This page describes the prerequisites for building a site that uses Docsy as a Hugo Module.
+
+## Install Hugo 
+
+You need a [recent **extended** version](https://github.com/gohugoio/hugo/releases) (we recommend version 0.73.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/).
+
+### On 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.73` 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
+
+### On 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 installed:
+
+```
+$ go version
+go version go1.17.6 windows/amd64
+```
+
+Ensure that you are using version 1.12 or higher.
+
+If the `go` language is not installed on your system yet or if you need to upgrade, go 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.
+
+
+## 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.35.1.windows.1
+```
+
+If no `git` client is installed on your system yet, go 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, choose 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/)
+
diff --git a/userguide/content/en/docs/Theme installation/Docsy-As-Module/start-from-scratch.md b/userguide/content/en/docs/Theme installation/Docsy-As-Module/start-from-scratch.md
new file mode 100644
index 0000000000..09302ed620
--- /dev/null
+++ b/userguide/content/en/docs/Theme installation/Docsy-As-Module/start-from-scratch.md	
@@ -0,0 +1,160 @@
+---
+title: "Create a new site: Start a new site from scratch"
+linkTitle: "Start a site from scratch"
+date: 2021-12-08T09:21:54+01:00
+weight: 3
+description: >
+  Create a new Hugo site from scratch with Docsy as a Hugo Module
+---
+
+The simplest approach to creating a Docsy site is [copying our example site](/docs/theme-installation/docsy-as-module/example-site-as-template/). However, if you're an experienced Hugo user or the site structure of our example site doesn't meet your needs, you may prefer to create a new site from scratch. With this option, you'll get Docsy look and feel, navigation, and other features, but you'll need to specify your own site structure. 
+
+These instructions give you a minimum file structure for your site project only, so that you build and extend your actual site step by step. The first step is adding the Docsy theme as a [Hugo Module](https://gohugo.io/hugo-modules/) to your site. If needed, you can easily [update](/docs/updating/) the module to the latest revision from the Docsy GitHub repo.
+
+## TL;DR: Setup for the impatient expert
+
+At your command prompt, run the following:
+
+{{< tabpane >}}
+{{< tab header="Unix shell" >}}
+hugo new site my-new-site
+cd  my-new-site
+hugo mod init github.com/me/my-new-site
+hugo mod get github.com/google/docsy@0.2.0-pre
+hugo mod get github.com/google/docsy/dependencies@0.2.0-pre
+cat >> config.toml <<EOL
+[module]
+[[module.imports]]
+path = "github.com/google/docsy"
+[[module.imports]]
+path = "github.com/google/docsy/dependencies"
+EOL
+hugo server
+{{< /tab >}}
+{{< tab header="Windows command line" >}}
+hugo new site my-new-site
+cd  my-new-site
+hugo mod init github.com/me/my-new-site
+hugo mod get github.com/google/docsy@0.2.0-pre
+hugo mod get github.com/google/docsy/dependencies@0.2.0-pre
+(echo [module]^
+
+[[module.imports]]^
+
+path = "github.com/google/docsy"^
+
+[[module.imports]]^
+
+path = "github.com/google/docsy/dependencies")>>config.toml
+hugo server
+{{< /tab >}}
+{{< /tabpane >}}
+
+
+You now can preview your new site inside your browser at [http://localhost:1313](http://localhost:1313/).
+
+## Detailed Setup instructions
+
+Specifying the [Docsy theme](https://github.com/google/docsy) as Hugo Module for your minimal site gives you all the theme-y goodness, but you'll need to specify your own site structure.
+
+### Create your new skeleton project
+
+To create a new Hugo site project and then add the Docs theme as a submodule, run the following commands from your project's root directory.
+
+```shell
+hugo new site my-new-site
+cd  my-new-site
+```
+
+This will create a minimal site structure, containing the folders `archetypes`, `content`, `data`, `layouts`, `static`, and `themes` and a configuration file, `config.toml.
+
+### Import the Docsy theme module as a dependency of your site
+
+Only sites that are Hugo Modules themselves can import other modules. To turn your site into a Hugo Module, run the following commands in your newly created site directory:
+
+```
+hugo mod init github.com/me/my-new-site
+```
+
+This creates two new files, `go.mod` for the module definitions and `go.sum` which holds the checksums for module verification.
+
+Next declare the Docsy theme module as a dependency for your site. You must also declare the submodule `dependencies` as a second dependency. This submodule pulls in both a workaround for a bug in Go's module management and the dependencies `bootstrap` and `Font-Awesome`.
+
+```
+hugo mod get github.com/google/docsy@0.2.0-pre
+hugo mod get github.com/google/docsy/dependencies@0.2.0-pre
+```
+
+These commands add both the `docsy` theme module and the `dependencies` submodule to your definition file `go.mod`.
+
+### Add theme module configuration settings
+
+Add the settings in the following snippet at the end of your site configuration file (default: `config.toml`) and save the file.
+
+{{< tabpane >}}
+{{< tab header="config.toml" >}}
+[module]
+  # uncomment line below for temporary local development of module
+  # replacements = "github.com/google/docsy -> ../../docsy"
+  [module.hugoVersion]
+    extended = true
+    min = "0.73.0"
+  [[module.imports]]
+    path = "github.com/google/docsy"
+    disable = false
+  [[module.imports]]
+    path = "github.com/google/docsy/dependencies"
+    disable = false
+{{< /tab >}}
+{{< tab header="config.yaml" >}}
+module:
+  hugoVersion:
+    extended: true
+    min: 0.73.0
+  imports:
+    - path: github.com/google/docsy
+      disable: false
+  imports:
+    - path: github.com/google/docsy/dependencies
+      disable: false
+{{< /tab >}}
+{{< tab header="config.json" >}}
+{
+  "module": {
+    "hugoVersion": {
+      "extended": true,
+      "min": "0.73.0"
+    },
+    "imports": [
+      {
+        "path": "github.com/google/docsy",
+        "disable": false
+      },
+      {
+        "path": "github.com/google/docsy/dependencies",
+        "disable": false
+      }
+    ]
+  }
+}
+{{< /tab >}}
+{{< /tabpane >}}
+
+### Preview your site
+
+To build and preview your site locally:
+
+```
+hugo server
+```
+
+By default, your site will be available at [http://localhost:1313](http://localhost:1313/). When encountering problems, have a look at the [known issues](/docs/getting-started/known_issues/#macos) on MacOS.
+
+You may get Hugo errors for missing parameters and values when you try to build your site. This is usually because you're missing default values for some configuration settings that Docsy uses - once you add them your site should build correctly. You can find out how to add configuration in [Basic site configuration](/docs/theme-installation/basic-configuration/) - we recommend copying the example site configuration even if you're creating a site from scratch as it provides defaults for many required configuration parameters.
+
+## What's next?
+
+* Add some [basic configuration](/docs/theme-installation/basic-configuration/)
+* [Add content and customize your site](/docs/adding-content/)
+* Get some ideas from our [Example Site](https://github.com/google/docsy-example) and other [Examples](/docs/examples/).
+* [Publish your site](/docs/deployment/).
diff --git a/userguide/content/en/docs/Theme installation/_index.md b/userguide/content/en/docs/Theme installation/_index.md
new file mode 100644
index 0000000000..96a0ddcfa0
--- /dev/null
+++ b/userguide/content/en/docs/Theme installation/_index.md	
@@ -0,0 +1,31 @@
+
+---
+title: "Get started"
+linkTitle: "Get started"
+weight: 2
+date: 2018-07-30
+description: >
+  Learn how to get started with Docsy, including the available options for installing and using the Docsy theme.
+---
+
+As you saw in our introduction, Docsy is a [Hugo](gohugo.io) theme, which means that if you want to use Docsy, you need to set up your website source so that the Hugo static site generator can find and use the Docsy theme files when building your site. The simplest way to do this is to copy and edit our example site, though we also provide instructions for adding the Docsy theme manually to new or existing sites.
+
+If you want to build and test your site locally you also need to be able to run Hugo itself, either by installing it and any other required dependencies, or by using our provided Docker container.
+
+This page describes Docsy's installation options and helps you choose the appropriate setup guide to get started.
+
+## Installation options
+
+Hugo offers multiple options for using themes, all of which are supported by Docsy.
+
+* **Adding the theme as a Hugo Module**: [Hugo Modules](https://gohugo.io/hugo-modules/) are the simplest and latest way to use Hugo themes. Hugo uses the modules mechanism to pull in the theme files from the main Docsy repo at your chosen revision, and it's easy to keep the theme up to date in your site. Our [example site](https://github.com/google/docsy-example) uses Docsy as a Hugo Module.
+* **Adding the theme as a Git submodule**: Adding the theme as a [Git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules) also lets Hugo use the theme files from their own repo, though is more complicated to maintain than the Hugo modules approach. This is the approach used in older versions of the Docsy example site and is still supported.
+* **Cloning the theme files**: If you don't want Hugo to have to get the theme files from an external repo (for example, if you want to customize and maintain your own copy of the theme directly, or your deployment choice requires you to include a copy of the theme in your repository), you can clone the files directly into your site source.
+
+## Migration and backward compatibility
+
+If you have an existing site that uses Docsy as a Git submodule, and you would like to update it to use Hugo Modules, follow our [migration guide](). If you're not ready to migrate yet, don't worry! Your site will continue to work as usual.
+
+## Setup guides
+
+Follow the setup guide for your chosen approach. If you're new to Docsy and not sure which guide to follow, we recommend following the Use Docsy as a Hugo Module guide as a simple and easily maintained option.
diff --git a/userguide/content/en/docs/Theme installation/basic-configuration.md b/userguide/content/en/docs/Theme installation/basic-configuration.md
new file mode 100644
index 0000000000..19875ea429
--- /dev/null
+++ b/userguide/content/en/docs/Theme installation/basic-configuration.md	
@@ -0,0 +1,54 @@
+---
+title: "Basic site configuration"
+linkTitle: "Basic site configuration"
+date: 2021-12-08T09:22:27+01:00
+weight: 4
+description: >
+  Basic configuration for new Docsy sites.
+---
+
+Site-wide configuration details and parameters are defined in your project's `config.toml` file. These include your chosen Hugo theme (Docsy, of course!), project name, community links, Google Analytics configuration, and Markdown parser parameters. See the examples with comments in [`config.toml` in the example project](https://github.com/google/docsy-example/blob/master/config.toml) for how to add this information. **We recommend copying this config.toml and editing it even if you’re just using the theme and not copying the entire Docsy example site**, as it includes default values for many parameters that you need to set for your site to build correctly.
+
+You may want to remove or customize some defaults of the copied `config.toml` file straight away:
+
+## Internationalization
+
+The copied `config.toml` file defines content in English, Norwegian and Farsi. You can find out more about how Docsy supports multi-language content in [Multi-language support](/docs/language/).
+
+If you don't intend to translate your site, you can remove the language switcher by removing the following lines from `config.toml`:
+
+```
+[languages.no]
+title = "Docsy"
+description = "Docsy er operativsystem for skyen"
+languageName ="Norsk"
+contentDir = "content/no"
+time_format_default = "02.01.2006"
+time_format_blog = "02.01.2006"
+
+[languages.fa]
+title = "اسناد گلدی"
+description = "یک نمونه برای پوسته داکسی"
+languageName ="فارسی"
+contentDir = "content/fa"
+time_format_default = "2006.01.02"
+time_format_blog = "2006.01.02"
+```
+
+## Search
+
+By default, the Docsy example site uses its own [Google Custom Search Engine](https://cse.google.com/cse/all). To disable this site search, delete or comment out the following lines:
+
+```
+# Google Custom Search Engine ID. Remove or comment out to disable search.
+gcs_engine_id = "011737558837375720776:fsdu1nryfng"
+```
+
+To use your own Custom Search Engine, replace the value in the `gcs_engine_id` with the ID of your own search engine. Or [choose another search option](/docs/adding-content/navigation/#site-search-options).
+
+
+## What's next?
+
+* [Add content and customize your site](/docs/adding-content/)
+* Get some ideas from our [Example Site](https://github.com/google/docsy-example) and other [Examples](/docs/examples/).
+* [Publish your site](/docs/deployment/).
diff --git a/userguide/content/en/docs/Theme installation/known_issues.md b/userguide/content/en/docs/Theme installation/known_issues.md
new file mode 100644
index 0000000000..638907a4d1
--- /dev/null
+++ b/userguide/content/en/docs/Theme installation/known_issues.md	
@@ -0,0 +1,55 @@
+---
+title: "Known issues"
+linkTitle: "Known issues"
+date: 2021-12-08T09:22:27+01:00
+weight: 4
+description: >
+  Known issues when installing Docsy theme.
+---
+
+The following issues are know on [MacOS](#macos) and on [Windows Subsystem for Linux](#windows-subsystem-for-linux-wsl):
+
+### MacOS
+
+#### Errors: `too many open files` or `fatal error: pipe failed`
+
+By default, MacOS permits a small number of open File Descriptors. For larger sites, or when you're simultaneously running multiple applications,
+you might receive one of the following errors when you run [`hugo server`](https://gohugo.io/commands/hugo_server/) to preview your site locally:
+
+* POSTCSS v7 and earlier:
+
+  ```
+  ERROR 2020/04/14 12:37:16 Error: listen tcp 127.0.0.1:1313: socket: too many open files
+  ```
+* POSTCSS v8 and later:
+
+  ```
+  fatal error: pipe failed
+  ```
+
+##### Workaround
+
+To temporarily allow more open files:
+
+1. View your current settings by running:
+
+   ```
+   sudo launchctl limit maxfiles
+   ```
+
+2. Increase the limit to `65535` files by running the following commands. If your site has fewer files, you can set choose to set lower soft (`65535`) and 
+   hard (`200000`) limits. 
+   
+   ```shell
+   sudo launchctl limit maxfiles 65535 200000
+   ulimit -n 65535
+   sudo sysctl -w kern.maxfiles=200000
+   sudo sysctl -w kern.maxfilesperproc=65535
+   ```
+
+Note that you might need to set these limits for each new shell. 
+[Learn more about these limits and how to make them permanent](https://www.google.com/search?q=mac+os+launchctl+limit+maxfiles+site%3Aapple.stackexchange.com&oq=mac+os+launchctl+limit+maxfiles+site%3Aapple.stackexchange.com).
+
+### Windows Subsystem for Linux (WSL)
+
+If you're using WSL, ensure that you're running `hugo` on a Linux mount of the filesystem, rather than a Windows one, otherwise you may get unexpected errors.
diff --git a/userguide/content/en/docs/Theme installation/other-options.md b/userguide/content/en/docs/Theme installation/other-options.md
new file mode 100644
index 0000000000..93e44ef10e
--- /dev/null
+++ b/userguide/content/en/docs/Theme installation/other-options.md	
@@ -0,0 +1,143 @@
+---
+title: "Other setup options"
+linkTitle: "Other setup options"
+date: 2021-12-08T09:22:27+01:00
+weight: 2
+description: >
+  Create a new Docsy site with Docsy as a Git submodule or cloned theme
+---
+
+If you don't want to use [Docsy as a Hugo Module](docs/theme-installation/docsy-as-module/) (for example if you do not want to install Go) but still don't want to copy the theme files into your own repo, you can **use Docsy as a [Git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules)**. Using submodules also lets Hugo use the theme files from Docsy repo, though is more complicated to maintain than the Hugo Modules approach. This is the approach used in older versions of the Docsy example site, and is still supported. If you are using Docsy as a submodule but would like to migrate to Hugo Modules, see our [migration guide]().
+
+Alternatively if you don’t want Hugo to have to get the theme files from an external repo (for example, if you want to customize and maintain your own copy of the theme directly, or your deployment choice requires you to include a copy of the theme in your repository), you can **clone the files directly into your site source**.
+
+This guide provides instructions for both these options, along with common prerequisites.
+
+## Prerequisites and installation
+
+### Install Hugo 
+
+You need a [recent **extended** version](https://github.com/gohugoio/hugo/releases) (we recommend version 0.73.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/).
+
+#### On 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.73` 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    
+
+#### On 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 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.
+
+## Other option 1: Use the theme as a submodule
+
+To create a new Hugo site project and then add the Docsy theme as a submodule, run the following commands from your project's root directory.
+
+```shell
+hugo new site myproject
+cd myproject
+git init
+git submodule add https://github.com/google/docsy.git themes/docsy
+echo 'theme = "docsy"' >> config.toml
+git submodule update --init --recursive
+```
+
+To add the Docsy theme to an existing site, run the following commands from your project's root directory:
+
+```
+git submodule add https://github.com/google/docsy.git themes/docsy
+echo 'theme = "docsy"' >> config.toml
+git submodule update --init --recursive
+```
+
+## Other option 2: Clone the Docsy theme
+
+If you don't want to use a submodules (for example, if you want to customize and maintain your  own copy of the theme directly, or your deployment choice requires you to include a copy of the theme in your repository), you can clone the theme into your project's `themes` subdirectory.
+
+To clone Docsy into your project's `theme` folder, run the following commands from your project's root directory:
+
+```
+cd themes
+git clone https://github.com/google/docsy
+```
+
+If you want to build and/or serve your site [locally](/docs/deployment/#serving-your-site-locally), you also need to get local copies of the theme’s own submodules:
+
+```
+git submodule update --init --recursive
+```
+
+For more information, see [Theme Components](https://gohugo.io/hugo-modules/theme-components/) on the [Hugo](https://gohugo.io) site.
+
+## Preview your site
+
+To build and preview your site locally:
+
+```
+cd myproject
+hugo server
+```
+    
+By default, your site will be available at http://localhost:1313/. [See the known issues on MacOS](#known-issues).
+
+You may get Hugo errors for missing parameters and values when you try to build your site. This is usually because you’re missing default values for some configuration settings that Docsy uses - once you add them your site should build correctly. You can find out how to add configuration in [Basic site configuration](/docs/theme-installation/basic-configuration/) - we recommend copying the example site configuration even if you’re creating a site from scratch as it provides defaults for many required configuration parameters.
+
+
+## What's next?
+
+* Add some [basic site configuration](/docs/theme-installation/basic-configuration/)
+* [Add content and customize your site](/docs/adding-content/)
+* Get some ideas from our [Example Site](https://github.com/google/docsy-example) and other [Examples](/docs/examples/).
+* [Publish your site](/docs/deployment/).
diff --git a/userguide/content/en/docs/Getting started/quickstart-docker.md b/userguide/content/en/docs/Theme installation/quickstart-docker.md
old mode 100755
new mode 100644
similarity index 87%
rename from userguide/content/en/docs/Getting started/quickstart-docker.md
rename to userguide/content/en/docs/Theme installation/quickstart-docker.md
index ca1a8d2ba1..db3f4d365e
--- a/userguide/content/en/docs/Getting started/quickstart-docker.md	
+++ b/userguide/content/en/docs/Theme installation/quickstart-docker.md	
@@ -1,13 +1,16 @@
 
 ---
-title: "Docker Quickstart"
-linkTitle: "Docker Quickstart"
+title: "Deploy Docsy inside a Docker container"
+linkTitle: "Deploy Docsy inside a Docker container"
 weight: 3
 date: 2018-07-30
 description: >
-  This page helps you to setup and run a local Docsy site with Docker in 5 minutes. 
+  Instructions on how to setup and run a local Docsy site with Docker.
 ---
 
+We provide a Docker image that you can use to run and test your Docsy site
+locally, without having to install all Docsy's dependencies.
+
 ## Install the prerequisites
 
 1. On Mac and Windows, download and install [Docker
diff --git a/userguide/content/en/docs/Updating/Convert-site-to-module.md b/userguide/content/en/docs/Updating/Convert-site-to-module.md
new file mode 100644
index 0000000000..7790b249b6
--- /dev/null
+++ b/userguide/content/en/docs/Updating/Convert-site-to-module.md
@@ -0,0 +1,205 @@
+---
+title: "Migrate to Hugo Modules"
+linkTitle: "Migrate to Hugo Modules"
+weight: 3
+description: >
+  Convert an existing site to use Docsy as a Hugo Module
+---
+
+## TL;DR: Conversion for the impatient expert
+
+Run the following from the command line:
+
+{{< tabpane >}}
+{{< tab header="Unix shell" >}}
+cd /path/to/my-existing-site
+hugo mod init github.com/me-at-github/my-existing-site
+hugo mod get github.com/google/docsy@0.2.0-pre
+hugo mod get github.com/google/docsy/dependencies@0.2.0-pre
+sed -i '/theme = \["docsy"\]/d' config.toml
+cat >> config.toml <<EOL
+[module]
+[[module.imports]]
+path = "github.com/google/docsy"
+[[module.imports]]
+path = "github.com/google/docsy"
+EOL
+hugo server
+{{< /tab >}}
+{{< tab header="Windows command line" >}}
+cd  my-existing-site
+hugo mod init github.com/me-at-github/my-existing-site
+hugo mod get github.com/google/docsy@0.2.0-pre
+hugo mod get github.com/google/docsy/dependencies@0.2.0-pre
+findstr /v /c:"theme = [\"docsy\"]" config.toml > config.toml.temp
+move /Y config.toml.temp config.toml
+(echo [module]^
+
+[[module.imports]]^
+
+path = "github.com/google/docsy"^
+
+[[module.imports]]^
+
+path = "github.com/google/docsy")>>config.toml
+hugo server
+{{< /tab >}}
+{{< /tabpane >}}
+
+
+## Detailed conversion instructions
+
+### Import the Docsy theme module as a dependency of your site
+
+At the command prompt, change to the root directory of your existing site.
+
+```
+cd /path/to/my-existing-site
+```
+
+Only sites that are Hugo Modules themselves can import other Hugo Modules. Turn your existing site into a Hugo Module by running the following command from your site directory, replacing `github.com/me/my-existing-site` with your site repository:
+
+```
+hugo mod init github.com/me/my-existing-site
+```
+
+This creates two new files, `go.mod` for the module definitions and `go.sum` which holds the checksums for module verification.
+
+Next declare the Docsy theme module as a dependency for your site. You must also declare the submodule `dependencies` as a second dependency. This submodule pulls in both a workaround for a bug in Go’s module management and the dependencies `bootstrap` and `Font-Awesome`.
+
+```
+hugo mod get github.com/google/docsy@0.2.0-pre
+hugo mod get github.com/google/docsy/dependencies@0.2.0-pre
+```
+
+These commands add both the `docsy` theme module and the `dependencies` submodule to your definition file `go.mod`.
+
+### Update your config file
+
+In your `config.toml` file, update the theme setting to use Hugo Modules. Find the following line:
+
+```
+theme = ["docsy"]
+```
+
+Change this line to:
+
+```
+theme = ["github.com/google/docsy", "github.com/google/docsy/dependencies"]
+```
+
+Alternatively, you can omit this line altogether and replace it with the settings given in the following snippet:
+
+{{< tabpane >}}
+{{< tab header="config.toml" >}}
+[module]
+  # uncomment line below for temporary local development of module
+  # replacements = "github.com/google/docsy -> ../../docsy"
+  [module.hugoVersion]
+    extended = true
+    min = "0.73.0"
+  [[module.imports]]
+    path = "github.com/google/docsy"
+    disable = false
+  [[module.imports]]
+    path = "github.com/google/docsy/dependencies"
+    disable = false
+{{< /tab >}}
+{{< tab header="config.yaml" >}}
+module:
+  hugoVersion:
+    extended: true
+    min: 0.73.0
+  imports:
+    - path: github.com/google/docsy
+      disable: false
+  imports:
+    - path: github.com/google/docsy/dependencies
+      disable: false
+{{< /tab >}}
+{{< tab header="config.json" >}}
+{
+  "module": {
+    "hugoVersion": {
+      "extended": true,
+      "min": "0.73.0"
+    },
+    "imports": [
+      {
+        "path": "github.com/google/docsy",
+        "disable": false
+      },
+      {
+        "path": "github.com/google/docsy/dependencies",
+        "disable": false
+      }
+    ]
+  }
+}
+{{< /tab >}}
+{{< /tabpane >}}
+
+{{% alert title="Attention" color="warning" %}}
+If you have a multi language installation, please make sure that the section `[languages]` inside your `config.toml` is declared before the section `[module]` with the module imports. Otherwise you will run into trouble!
+{{% /alert %}}
+
+### Check validity of your configuration settings
+
+To make sure that your configuration settings are correct, run the command `hugo mod graph` which prints a module dependency graph:
+
+```
+hugo mod graph
+hugo: collected modules in 1092 ms
+github.com/me/my-existing-site github.com/google/docsy@0.2.0-pre
+github.com/me/my-existing-site github.com/google/docsy/dependencies@0.2.0-pre
+github.com/google/docsy/dependencies@0.2.0-pre github.com/twbs/bootstrap@v4.6.1+incompatible
+github.com/google/docsy/dependencies@0.2.0-pre github.com/FortAwesome/Font-Awesome@v0.0.0-20210804190922-7d3d774145ac
+```
+
+Make sure that three lines with dependencies `docsy`, `bootstrap` and `Font-Awesome` are listed. If not, please double check your config settings.
+
+{{% alert title="Tip" %}}
+In order to clean up your module cache, issue the command `hugo mod clean`
+
+```
+hugo mod clean
+hugo: collected modules in 995 ms
+hugo: cleaned module cache for "github.com/FortAwesome/Font-Awesome"
+hugo: cleaned module cache for "github.com/google/docsy"
+hugo: cleaned module cache for "github.com/google/docsy/dependencies"
+hugo: cleaned module cache for "github.com/twbs/bootstrap"
+```
+{{% /alert %}}
+
+### Clean up your repository
+
+Since your site now uses Hugo Modules, your previously used `themes` directory can be removed: 
+
+```
+rm -rf /path/to/your/theme
+```
+
+If your Docsy theme was installed as submodule, you can remove the theme submodule:
+
+```
+git rm --cached /path/to/your/submodule/theme
+git add .
+```
+
+With your submodule deleted, now delete the relevant line from the hidden submodule definition file `.gitmodules`, too. If this is the only line, you can delete the file altogether.
+
+```
+rm .gitmodules
+```
+
+Finally, delete the now untracked submodule files and also clean up the internal directory that git used to store your git submodules:
+
+```
+rm -rf /path/to/your/submodule/theme
+rm -rf .git/modules
+```
+
+
+{{% alert title="Attention" color="warning" %}}
+Be careful when using the `rm -rf` command, make sure that you don't inadvertently delete any productive data files!
+{{% /alert %}}
diff --git a/userguide/content/en/docs/Updating/Updating-hugo-module.md b/userguide/content/en/docs/Updating/Updating-hugo-module.md
new file mode 100644
index 0000000000..d72527ee56
--- /dev/null
+++ b/userguide/content/en/docs/Updating/Updating-hugo-module.md
@@ -0,0 +1,40 @@
+---
+title: "Update the Docsy Hugo Module"
+linkTitle: "Update the Docsy Hugo Module"
+weight: 1
+description: >
+  Update the Docsy theme to the latest version using Hugo Modules.
+---
+
+When using the Docsy theme as a Hugo Module, updating your theme is really easy.
+
+At the command prompt, change to the root directory of your existing site.
+
+```
+cd /path/to/my-existing-site
+```
+
+Then invoke hugo's module `get` subcommand with the update flag:
+
+```
+hugo mod get -u github.com/google/docsy
+```
+
+Hugo automatically pulls in the latest theme version. That's it, your update is done!
+
+
+{{% alert title="Tip" %}}
+If you want to set your module to a certain version inside the docsy theme repo, simply specific the name of the tag representing this version (here: _0.2.0_) when updating your theme:
+
+```
+hugo mod get -u github.com/google/docsy@0.2.0
+```
+
+Instead of a version tag, you can also specify a commit hash inside the repo (here: _c7b9901e_) when updating your theme:
+
+
+```
+hugo mod get -u github.com/google/docsy@c7b9901e
+```
+{{% /alert %}}
+
diff --git a/userguide/content/en/docs/Updating/Updating-submodules.md b/userguide/content/en/docs/Updating/Updating-submodules.md
new file mode 100644
index 0000000000..f29aa01641
--- /dev/null
+++ b/userguide/content/en/docs/Updating/Updating-submodules.md
@@ -0,0 +1,52 @@
+---
+title: "Update Docsy without Hugo Modules"
+linkTitle: "Update Docsy without Hugo Modules"
+weight: 2
+description: >
+  Update the Docsy theme to the latest version using submodules or `git pull`.
+---
+
+If you aren't using Hugo Modules, depending on how you chose to install Docsy on your existing site, use one of the following two procedures to update your theme.
+
+{{% alert title="Tip" %}}
+If you intend to update your site, consider [converting your site to Hugo Modules](/docs/updating/convert-site-to-module/). After conversion, it's even simpler to update Docsy!
+{{% /alert %}}
+
+## Update your Docsy submodule
+
+If you are using the [Docsy theme as a submodule](/docs/theme-installation/other-options/#other-option-1-use-the-theme-as-a-submodule) in your project, here's how you update the submodule:
+
+1. Navigate to the root of your local project, then run:
+
+        git submodule update --remote
+
+    
+1. Add and then commit the change to your project:
+
+        git add themes/
+        git commit -m "Updating theme submodule"
+
+
+1. Push the commit to your project repo. For example, run:
+
+        git push origin master
+
+
+## Route 2: Update your Docsy clone
+
+If you [cloned the Docsy theme](/docs/theme-installation/other-options/#other-option-2-clone-the-docsy-theme) into
+the `themes` folder in your project, then you use the `git pull` command:
+
+1. Navigate to the `themes` directory in your local project:
+
+        cd themes
+
+1. Ensure that `origin` is set to `https://github.com/google/docsy.git`:
+
+        git remote -v
+
+1. Update your local clone:
+
+        git pull origin master
+
+If you have made any local changes to the cloned theme, **you must manually resolve any merge conflicts**.
diff --git a/userguide/content/en/docs/Updating/_index.md b/userguide/content/en/docs/Updating/_index.md
index f7dc2a7843..8ad20f162b 100644
--- a/userguide/content/en/docs/Updating/_index.md
+++ b/userguide/content/en/docs/Updating/_index.md
@@ -1,59 +1,19 @@
 ---
-title: "Updating Docsy"
-linkTitle: "Updating Docsy"
+title: "Update Docsy"
+linkTitle: "Update Docsy"
 weight: 8
 description: >
- Keeping the theme up to date.
+ Keeping the Docsy theme up to date.
 ---
 
 We hope to continue to make improvements to the theme [along with the Docsy community](/docs/contribution-guidelines/). 
-If you have cloned the example site (or are otherwise using the theme as a submodule), you can update the Docsy theme
-yourself. 
+If you have cloned the example site (or are otherwise using the theme as a Hugo Module or Git submodule), you can easily update the Docsy theme in your site yourself. If you have cloned the theme itself into your own project you can also update, though you may need to resolve merge conflicts.
 
 Updating Docsy means that your site will build using the latest version of Docsy at `HEAD` and include 
 all the new commits or changes that have been merged since the point in time that you initially added the Docsy 
 submodule, or last updated. Updating won't affect any modifications that you made in your own project to 
 [override the Docsy look and feel](/docs/adding-content/lookandfeel/), as your overrides 
-don't modify the theme itself. For details about what has changed in the theme, see the list of 
+don't modify the theme itself. For details about what has changed in the theme since your last update, see the list of 
 [Docsy commits](https://github.com/google/docsy/commits/main).
 
-Depending on how you chose to use Docsy, follow the corresponding steps to update the theme:
-
-## Update a Docsy submodule
-
-If you are using the Docsy theme as a submodule in your project (for example, if you've copied our example site), you update the submodule:
-
-1. Navigate to the root of your local project, then run:
-
-        git submodule update --remote
-
-    
-1. Add and then commit the change to your project:
-
-        git add themes/
-        git commit -m "Updating theme submodule"
-
-
-1. Push the commit to your project repo. For example, run:
-
-        git push origin main
-
-    
-## Update your Docsy clone
-
-If you [cloned the Docsy theme](/docs/getting-started/#cloning-the-docsy-theme-to-your-projects-themes-subdirectory) into
-the `themes` folder in your project, then you use the `git pull` command:
-
-1. Navigate to the `themes` directory in your local project:
-
-        cd themes
-
-1. Ensure that `origin` is set to `https://github.com/google/docsy.git`:
-
-        git remote -v
-
-1. Update your local clone:
-
-        git pull origin main
-
-If you have made any local changes to the cloned theme, you must manually resolve any merge conflicts.
+If you have been using the theme as a Git submodule, you can also update your site to use [Docsy as a Hugo Module](/docs/theme-installation/docsy-as-module/). This is the latest and simplest way to pull in a Hugo theme from its repository. If you're not ready to migrate to Hugo Modules yet, don't worry, your site will still work and you can continue to update your submodule as before.
diff --git a/userguide/content/en/docs/_index.md b/userguide/content/en/docs/_index.md
index 4270ba24d9..16750c46cf 100755
--- a/userguide/content/en/docs/_index.md
+++ b/userguide/content/en/docs/_index.md
@@ -38,6 +38,6 @@ If you'd like to use Docsy's layouts but prefer to use Jekyll, [vsoch](https://g
 
 ## Ready to get started?
 
-Find out how to build and serve your first site in [Getting Started](./getting-started/). Or visit the [example site](https://example.docsy.dev) and [its repo](https://github.com/google/docsy-example) and start exploring!
+Find out how to build and serve your first site in [Get Started](/docs/theme-installation/). Or visit the [example site](https://example.docsy.dev) and [its repo](https://github.com/google/docsy-example) and start exploring!