User guide: reflect latest changes in hugo module implementation

userguide/.gitignore

@@ -2,3 +2,5 @@
 .hugo_build.lock
 /public
 resources/
+# Themes
+themes/

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
 

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.75` 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" %}}

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

@@ -14,7 +14,7 @@ As beginner, it is recommended that you use the sources of the [Docsy example si
 At your Unix shell or your Windows command line, issue:
 
 ```
-git clone https://github.com/google/docsy.git my-new-site
+git clone -b sandbox https://github.com/google/docsy-example.git my-new-site
 cd  my-new-site
 hugo server
 ```
@@ -36,17 +36,17 @@ If you do have a GitHub account and additionally want to create a remote GitHub
 
 #### 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`):
+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 repo 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
+git clone -b sandbox 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. 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**.
 
@@ -62,7 +62,7 @@ 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::
+To build and preview your site locally, switch to the root of your cloned project and use hugo's `server` subcommand::
 
 ```
 cd my-new-site

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

@@ -11,7 +11,7 @@ description: >
 
 ### 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. 
+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/).
 
@@ -24,7 +24,7 @@ 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:
+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
@@ -64,13 +64,13 @@ Hugo's commands for module management require that the Go programming language i
 
 ```
 $ go version
-go version go1.17.5 windows/amd64
+go version go1.17.6 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.
+Make sure you are using go version 1.12 or higher, otherwise you might run in trouble.
 {{% /alert %}}
 
 ### Install Git VCS client
@@ -79,7 +79,7 @@ Hugo's commands for module management require that the git client is installed o
 
 ```
 git version
-git version 2.34.1.windows.1
+git version 2.35.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.

userguide/content/en/docs/Theme installation/Docsy-As-Module/start-from-scratch.md

@@ -19,31 +19,32 @@ At your command prompt, issue:
 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
+hugo mod get github.com/google/docsy@v0.2.0-pre
+hugo mod get github.com/google/docsy/module@v0.2.0-pre
 cat >> config.toml <<EOL
 [module]
 [[module.imports]]
 path = "github.com/google/docsy"
+[[module.imports]]
+path = "github.com/google/docsy/module"
 EOL
-mkdir -p assets/vendor/bootstrap/scss/vendor
-wget -P assets/vendor/bootstrap/scss/vendor https://raw.githubusercontent.com/twbs/bootstrap/v4.6.1/scss/vendor/_rfs.scss
 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
+hugo mod get github.com/google/docsy@v0.2.0-pre
+hugo mod get github.com/google/docsy/module@v0.2.0-pre
 (echo [module]^
 
 [[module.imports]]^
 
-path = "github.com/google/docsy")>>config.toml
-md assets\vendor\bootstrap\scss\vendor
-cd assets\vendor\bootstrap\scss\vendor
-REM Windows 10 only
-curl.exe -O --url https://raw.githubusercontent.com/twbs/bootstrap/v4.6.1/scss/vendor/_rfs.scss
-cd ..\..\..\..\..
+path = "github.com/google/docsy"^
+
+[[module.imports]]^
+
+path = "github.com/google/docsy/module")>>config.toml
 hugo server
 {{< /tab >}}
 {{< /tabpane >}}
@@ -74,15 +75,16 @@ Only sites that are hugo modules themselves can import other hugo modules. So tu
 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.
+This will create two new files, `go.mod` for the module definitions and `go.sum` which holds the checksums for module verification.
 
-Afterwards, declare the docsy module as a dependency for your site:
+Afterwards, declare the docsy theme module as a dependency for your site. Also declare the submodule `module` as a second dependency. The submodule will pull 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
+hugo mod get github.com/google/docsy@v0.2.0-pre
+hugo mod get github.com/google/docsy/module@v0.2.0-pre
 ```
 
-This will add the docsy theme module to your definition file `go.mod`.
+These commands will add both the docsy theme module and the submodule to your definition file `go.mod`.
 
 ### Add theme module configuration settings
 
@@ -95,31 +97,41 @@ Next, add the settings given in the code box below at the end of your site confi
   # replacements = "github.com/google/docsy -> ../../docsy"
   [module.hugoVersion]
     extended = true
-    min = "0.75.0"
+    min = "0.73.0"
   [[module.imports]]
     path = "github.com/google/docsy"
     disable = false
+  [[module.imports]]
+    path = "github.com/google/docsy/module"
+    disable = false
 {{< /tab >}}
 {{< tab header="config.yaml" >}}
 module:
   hugoVersion:
     extended: true
-    min: 0.75.0
+    min: 0.73.0
   imports:
     - path: github.com/google/docsy
       disable: false
+  imports:
+    - path: github.com/google/docsy/module
+      disable: false
 {{< /tab >}}
 {{< tab header="config.json" >}}
 {
   "module": {
     "hugoVersion": {
       "extended": true,
-      "min": "0.75.0"
+      "min": "0.73.0"
     },
     "imports": [
       {
         "path": "github.com/google/docsy",
         "disable": false
+      },
+      {
+        "path": "github.com/google/docsy/module",
+        "disable": false
       }
     ]
   }
@@ -129,42 +141,6 @@ module:
 
  Store the file, and your site configuration is finished.
 
-### Work around a known bug in Go's module management
-
-When using `bootstrap` dependency as module, we are affected by a [known](https://github.com/golang/go/issues/37397) bug in Go's core module library. This bug won't be fixed, fortunately we can work around it:
-
-All we have to do is to place a file `_rfs.scss` at the bottom of a new directory structure inside our site:
-
-```
-my-new-site
-│
-└───assets
-    │
-    └───vendor
-        │
-        └───bootstrap
-            │
-            └───scss
-                │
-                └───vendor
-                    │
-                    └───_rfs.scss
-
-```
-
-First we create the needed directory structure using the `mkdir` command:
-
-```shell
-mkdir -p assets/vendor/bootstrap/scss/vendor
-```
-
-Then we download the file `_rfs.scss` using the `wget` command line utility:
-
-```shell
-wget -P assets/vendor/bootstrap/scss/vendor https://raw.githubusercontent.com/twbs/bootstrap/v4.6.1/scss/vendor/_rfs.scss
-```
-
-
 ### Preview your site
 
 To build and preview your site locally:

userguide/content/en/docs/Theme installation/quickstart-clone-git-repo.md

@@ -13,7 +13,7 @@ Traditionally, Docsy theme is installed by cloning either the repo of the Docsy
 
 ### 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. 
+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/).
 
@@ -26,7 +26,7 @@ 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:
+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