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..c8475a4420
--- /dev/null
+++ b/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.
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..8ad7493963
--- /dev/null
+++ b/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.
+
+
+ git clone https://github.com/me-at-github/my-new-site.git
+
+
+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/).
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..801e04e3e1
--- /dev/null
+++ b/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/)
+
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..4bcd72384c
--- /dev/null
+++ b/userguide/content/en/docs/Theme installation/Docsy-As-Module/start-from-scratch.md
@@ -0,0 +1,278 @@
+---
+title: "Route 2: Start your new hugo site from scratch (for experts)"
+linkTitle: "Start site from scratch (experts)"
+date: 2021-12-08T09:21:54+01:00
+weight: 3
+description: >
+ Instructions on how to start a hugo site from scratch using Docsy theme as Hugo module which is automatically pulled in.
+---
+
+As an expert, you may prefer your new site from scratch. This approach gives you a minimum skeleton structure for your site only, so that you build and extend your 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 version of the Docsy GitHub repo.
+
+
+## TL;DR: Setup for the impatient expert
+
+At your command prompt, issue:
+
+{{< 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
+cat >> config.toml <}}
+{{< 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
+(echo [module]^
+
+[[module.imports]]^
+
+path = "github.com/google/docsy"^
+
+[[module.imports.mounts]]^
+
+source = "assets"^
+
+target = "assets"^
+
+[[module.imports.mounts]]^
+
+source = "assets/bootstrap/scss/vendor"^
+
+target = "assets/vendor/bootstrap/scss/vendor"^
+
+[[module.imports.mounts]]^
+
+source = "i18n"^
+
+target = "i18n"^
+
+[[module.imports.mounts]]^
+
+source = "layouts"^
+
+target = "layouts"^
+
+[[module.imports.mounts]]^
+
+source = "static"^
+
+target = "static")>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 site
+
+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.
+
+### Add the Docsy theme module to your site
+
+Only sites that are hugo modules themselves can import other hugo modules. So turn your site into a Hugo Module by executing the following commands from within your newly created site directory:
+
+```
+hugo mod init github.com/me/my-new-site
+```
+
+This will create two new files, `go.mod` for the module definitions and `go.sum` which helds the checksums for module verification.
+
+Afterwards, declare the docsy module as a dependency for your site:
+
+```
+hugo mod get github.com/google/docsy
+```
+
+This will add the docsy theme module to your definition file `go.mod`.
+
+### Add theme module configuration settings
+
+Next, add the settings given in the code box below at the end of your site configuration file (default: `config.toml`).
+
+{{< 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.75.0"
+ [[module.imports]]
+ path = "github.com/google/docsy"
+ disable = false
+ [[module.imports.mounts]]
+ source = "assets"
+ target = "assets"
+ [[module.imports.mounts]]
+ source = "assets/bootstrap/scss/vendor"
+ target = "assets/vendor/bootstrap/scss/vendor"
+ [[module.imports.mounts]]
+ source = "i18n"
+ target = "i18n"
+ [[module.imports.mounts]]
+ source = "layouts"
+ target = "layouts"
+ [[module.imports.mounts]]
+ source = "static"
+ target = "static"
+{{< /tab >}}
+{{< tab header="config.yaml" >}}
+module:
+ hugoVersion:
+ extended: true
+ min: 0.75.0
+ imports:
+ - path: github.com/google/docsy
+ disable: false
+ mounts:
+ - source: assets
+ target: assets
+ - source: assets/bootstrap/scss/vendor
+ target: assets/vendor/bootstrap/scss/vendor
+ - source: i18n
+ target: i18n
+ - source: layouts
+ target: layouts
+ - source: static
+ target: static
+{{< /tab >}}
+{{< tab header="config.json" >}}
+{
+ "module": {
+ "hugoVersion": {
+ "extended": true,
+ "min": "0.75.0"
+ },
+ "imports": [
+ {
+ "path": "github.com/google/docsy",
+ "disable": false,
+ "mounts": [
+ {
+ "source": "assets",
+ "target": "assets"
+ },
+ {
+ "source": "assets/bootstrap/scss/vendor",
+ "target": "assets/vendor/bootstrap/scss/vendor"
+ },
+ {
+ "source": "i18n",
+ "target": "i18n"
+ },
+ {
+ "source": "layouts",
+ "target": "layouts"
+ },
+ {
+ "source": "static",
+ "target": "static"
+ }
+ ]
+ }
+ ]
+ }
+}
+{{< /tab >}}
+{{< /tabpane >}}
+
+ Store the file, and your site configuration is finished.
+
+
+### 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](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. These errors will go away once you did your basic site configuration as described in the next chapter.
+
+## 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.**. Pleas note that this file is not bound to the Docsy example site, it will be useful for your project, too.
+
+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/_index.md b/userguide/content/en/docs/Theme installation/_index.md
new file mode 100644
index 0000000000..e4831311c7
--- /dev/null
+++ b/userguide/content/en/docs/Theme installation/_index.md
@@ -0,0 +1,14 @@
+
+---
+title: "Theme Installation"
+linkTitle: "Theme Installation"
+weight: 2
+date: 2018-07-30
+description: >
+ This page tells about the three different ways to install and make use of the Docsy theme.
+---
+
+### Three Options To Install Docsy Theme
+
+Below three different options of installing Docsy theme are listed.
+If you are unsure which option to select, choose the first one, which is considered as a both simple and forward-looking way to install the Docsy theme.
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/Getting started/_index.md b/userguide/content/en/docs/Theme installation/quickstart-clone-git-repo.md
old mode 100755
new mode 100644
similarity index 83%
rename from userguide/content/en/docs/Getting started/_index.md
rename to userguide/content/en/docs/Theme installation/quickstart-clone-git-repo.md
index ddcb33a468..15da9a0f88
--- a/userguide/content/en/docs/Getting started/_index.md
+++ b/userguide/content/en/docs/Theme installation/quickstart-clone-git-repo.md
@@ -1,25 +1,16 @@
-
---
-title: "Getting Started"
-linkTitle: "Getting Started"
+title: "Option 2: Cloning the Docsy Theme from a GitHub Repo (Traditional)"
+linkTitle: "Cloning GitHub Repo (Traditional)"
+date: 2021-12-08T09:22:27+01:00
weight: 2
-date: 2018-07-30
description: >
- This page tells you how to get started with the Docsy theme, including installation and basic configuration.
+ Instructions on traditional installation and basic configuration of the Docsy theme by cloning the Docsy GitHub repo.
---
+Traditionally, Docsy theme is installed by cloning either the repo of the Docsy example site or by cloning the docsy repo for usage a local theme of your site. Below, you can find step-by-step instructions on how to install Docsy this way.
## 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) (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.
@@ -40,7 +31,7 @@ If the result is `v0.75` or earlier, or if you don't see `Extended`, you'll need
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.5X_Linux-64bit.tar.gz`).
+3. Download the latest extended version (`hugo_extended_0.9X_Linux-64bit.tar.gz`).
4. Create a new directory:
mkdir hugo
@@ -117,7 +108,7 @@ This is the simplest approach, as the Docsy example site repo is a [template rep
git clone --recurse-submodules --depth 1 https://github.com/my/example.git
-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`.
+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](/docs/getting-started/known_issues/#macos)). 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
@@ -180,7 +171,7 @@ your repo that may result in merge conflicts when you try to update it. This is
[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.
+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
@@ -275,56 +266,9 @@ 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/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..f817433105
--- 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: "Option 3: 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..e1d46fd6d7
--- /dev/null
+++ b/userguide/content/en/docs/Updating/Convert-site-to-module.md
@@ -0,0 +1,226 @@
+---
+title: "Convert an existing site to Docsy hugo module"
+linkTitle: "Convert existing site to Docsy hugo module"
+weight: 3
+description: >
+ Convert an existing site, turning Hugo Docsy theme into a hugo module.
+---
+
+## TL;DR: Conversion for the impatient expert
+
+At your command prompt, issue:
+
+{{< 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
+cat >> config.toml <}}
+{{< 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
+(echo [module]^
+
+[[module.imports]]^
+
+path = "github.com/google/docsy"^
+
+[[module.imports.mounts]]^
+
+source = "assets"^
+
+target = "assets"^
+
+[[module.imports.mounts]]^
+
+source = "assets/bootstrap/scss/vendor"^
+
+target = "assets/vendor/bootstrap/scss/vendor"^
+
+[[module.imports.mounts]]^
+
+source = "i18n"^
+
+target = "i18n"^
+
+[[module.imports.mounts]]^
+
+source = "layouts"^
+
+target = "layouts"^
+
+[[module.imports.mounts]]^
+
+source = "static"^
+
+target = "static")>config.toml
+hugo server
+{{< /tab >}}
+{{< /tabpane >}}
+
+
+## Detailed Setup instructions
+
+### Add the Docsy theme module to 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. So turn your existing site into a Hugo Module by executing the following commands from within your site directory:
+
+```
+hugo mod init github.com/me/my-existing-site
+```
+
+This will create two new files, `go.mod` for the module definitions and `go.sum` which helds the checksums for module verification.
+
+Afterwards, declare the docsy module as a dependency for your site:
+
+```
+hugo mod get github.com/google/docsy
+```
+
+This will add the docsy theme module to your definition file `go.mod`.
+
+### Add theme module configuration settings
+
+Next, add the settings given in the code box below at the end of your site configuration file (default: `config.toml`).
+
+{{< 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.75.0"
+ [[module.imports]]
+ path = "github.com/google/docsy"
+ disable = false
+ [[module.imports.mounts]]
+ source = "assets"
+ target = "assets"
+ [[module.imports.mounts]]
+ source = "assets/bootstrap/scss/vendor"
+ target = "assets/vendor/bootstrap/scss/vendor"
+ [[module.imports.mounts]]
+ source = "i18n"
+ target = "i18n"
+ [[module.imports.mounts]]
+ source = "layouts"
+ target = "layouts"
+ [[module.imports.mounts]]
+ source = "static"
+ target = "static"
+{{< /tab >}}
+{{< tab header="config.yaml" >}}
+module:
+ hugoVersion:
+ extended: true
+ min: 0.75.0
+ imports:
+ - path: github.com/google/docsy
+ disable: false
+ mounts:
+ - source: assets
+ target: assets
+ - source: assets/bootstrap/scss/vendor
+ target: assets/vendor/bootstrap/scss/vendor
+ - source: i18n
+ target: i18n
+ - source: layouts
+ target: layouts
+ - source: static
+ target: static
+{{< /tab >}}
+{{< tab header="config.json" >}}
+{
+ "module": {
+ "hugoVersion": {
+ "extended": true,
+ "min": "0.75.0"
+ },
+ "imports": [
+ {
+ "path": "github.com/google/docsy",
+ "disable": false,
+ "mounts": [
+ {
+ "source": "assets",
+ "target": "assets"
+ },
+ {
+ "source": "assets/bootstrap/scss/vendor",
+ "target": "assets/vendor/bootstrap/scss/vendor"
+ },
+ {
+ "source": "i18n",
+ "target": "i18n"
+ },
+ {
+ "source": "layouts",
+ "target": "layouts"
+ },
+ {
+ "source": "static",
+ "target": "static"
+ }
+ ]
+ }
+ ]
+ }
+}
+{{< /tab >}}
+{{< /tabpane >}}
+
+ Store the file, and you conversion is done.
+
+### Remove theme and submodule leftovers
+
+Since your site makes now use of hugo modules, your previous used themes directory can be removed:
+
+```
+rm -rf /path/to/your/theme/*
+```
+
+If your docsy theme was installed as submodule, you may delete the hidden submodule definition file `.gitmodules`, too.
+
+```
+rm .gitmodules
+```
+
+Finally, you may clean up the internal directory that git used to store your git submodules:
+
+```
+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..76a794ea9d
--- /dev/null
+++ b/userguide/content/en/docs/Updating/Updating-hugo-module.md
@@ -0,0 +1,33 @@
+---
+title: "Update of Docsy theme if used as hugo module"
+linkTitle: "Update of Docsy (hugo module)"
+weight: 1
+description: >
+ Updating Docsy theme to latest version (for installations that use Docsy theme as **hugo module**).
+---
+
+When making use of Dosy theme as 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 will automatically pull 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 revision inside the docsy theme repo, simply specific the commit hash (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..9dcfdb2995
--- /dev/null
+++ b/userguide/content/en/docs/Updating/Updating-submodules.md
@@ -0,0 +1,52 @@
+---
+title: "Update of Docsy theme if used traditionally (no hugo module)"
+linkTitle: "Update of Docsy (no module)"
+weight: 2
+description: >
+ Updating Docsy theme to latest version (for traditional installations **not** using hugo as module).
+---
+
+{{% alert title="Tip" %}}
+If you intend to update your site, you might consider [converting your site to hugo modules](http://localhost:1313/docs/updating/convert-site-to-module/). After conversion, the update of your site is as simple as never before.
+{{% /alert %}}
+
+Depending on how you chose to install Docsy on your existing traditional site, use one of the following two routes to update your theme:
+
+## Route 1: Update your Docsy submodule
+
+If you are using the Docsy theme as a submodule in your project (for example, if you've copied our example site), that'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/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 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 f7f33d708d..5f24e964f7 100644
--- a/userguide/content/en/docs/Updating/_index.md
+++ b/userguide/content/en/docs/Updating/_index.md
@@ -1,9 +1,9 @@
---
-title: "Updating Docsy"
-linkTitle: "Updating Docsy"
+title: "Update of Docsy Theme of conversion of existing site to hugo modules"
+linkTitle: "Update or Conversion of Docsy Theme"
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/).
@@ -15,46 +15,4 @@ all the new commits or changes that have been merged since the point in time tha
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
-[Docsy commits](https://github.com/google/docsy/commits/master).
-
-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 master
-
-
-## 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 master
-
-If you have made any local changes to the cloned theme, you must manually resolve any merge conflicts.
-
+[Docsy commits](https://github.com/google/docsy/commits/master).
\ No newline at end of file
diff --git a/userguide/themes/docsy b/userguide/themes/docsy
new file mode 160000
index 0000000000..7dc7083746
--- /dev/null
+++ b/userguide/themes/docsy
@@ -0,0 +1 @@
+Subproject commit 7dc70837461881b639215e40d90b6502974e3a14