From cad8bfd1c643115da946dd87ff6e5cd3098725cd Mon Sep 17 00:00:00 2001 From: Andreas Deininger Date: Fri, 10 Dec 2021 14:26:28 +0100 Subject: [PATCH 01/37] User guide: adding instructions on how to use and update docsy as hugo module --- .../Docsy-As-Module/_index.md | 12 + .../example-site-as-template.md | 81 +++++ .../installation-prerequisites.md | 110 +++++++ .../Docsy-As-Module/start-from-scratch.md | 278 ++++++++++++++++++ .../en/docs/Theme installation/_index.md | 14 + .../docs/Theme installation/known_issues.md | 55 ++++ .../quickstart-clone-git-repo.md} | 70 +---- .../quickstart-docker.md | 9 +- .../docs/Updating/Convert-site-to-module.md | 226 ++++++++++++++ .../en/docs/Updating/Updating-hugo-module.md | 33 +++ .../en/docs/Updating/Updating-submodules.md | 52 ++++ userguide/content/en/docs/Updating/_index.md | 49 +-- 12 files changed, 878 insertions(+), 111 deletions(-) create mode 100644 userguide/content/en/docs/Theme installation/Docsy-As-Module/_index.md create mode 100644 userguide/content/en/docs/Theme installation/Docsy-As-Module/example-site-as-template.md create mode 100644 userguide/content/en/docs/Theme installation/Docsy-As-Module/installation-prerequisites.md create mode 100644 userguide/content/en/docs/Theme installation/Docsy-As-Module/start-from-scratch.md create mode 100644 userguide/content/en/docs/Theme installation/_index.md create mode 100644 userguide/content/en/docs/Theme installation/known_issues.md rename userguide/content/en/docs/{Getting started/_index.md => Theme installation/quickstart-clone-git-repo.md} (83%) mode change 100755 => 100644 rename userguide/content/en/docs/{Getting started => Theme installation}/quickstart-docker.md (87%) mode change 100755 => 100644 create mode 100644 userguide/content/en/docs/Updating/Convert-site-to-module.md create mode 100644 userguide/content/en/docs/Updating/Updating-hugo-module.md create mode 100644 userguide/content/en/docs/Updating/Updating-submodules.md 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 7ec116599a..78c632c75e --- 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) (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. @@ -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 f7dc2a7843..7b9ea5ecfe 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,45 +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/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. +[Docsy commits](https://github.com/google/docsy/commits/main). \ No newline at end of file From 49071eb255e9ee536a0cbcd3ef38c37f4f61bfef Mon Sep 17 00:00:00 2001 From: Andreas Deininger Date: Sat, 18 Dec 2021 14:32:12 +0100 Subject: [PATCH 02/37] Add section on how to work around a known bug in Go's module management --- .../content/en/docs/Deployment/_index.md | 2 +- .../Docsy-As-Module/start-from-scratch.md | 140 +++++----------- .../docs/Updating/Convert-site-to-module.md | 157 +++++++----------- 3 files changed, 102 insertions(+), 197 deletions(-) diff --git a/userguide/content/en/docs/Deployment/_index.md b/userguide/content/en/docs/Deployment/_index.md index 35a2e91029..ead5654a17 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.75` or later as its **Value**. 1. Click **Deploy site**. {{% alert title="Note" color="primary" %}} 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 index 4bcd72384c..1870d1fab4 100644 --- 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 @@ -24,22 +24,9 @@ cat >> config.toml <}} {{< tab header="Windows command line" >}} @@ -51,37 +38,12 @@ hugo mod get github.com/google/docsy [[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 +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 ..\..\..\.. hugo server {{< /tab >}} {{< /tabpane >}} @@ -137,21 +99,6 @@ Next, add the settings given in the code box below at the end of your site confi [[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: @@ -161,17 +108,6 @@ module: 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" >}} { @@ -183,29 +119,7 @@ module: "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" - } - ] + "disable": false } ] } @@ -215,13 +129,47 @@ 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: ``` -cd myproject hugo server ``` diff --git a/userguide/content/en/docs/Updating/Convert-site-to-module.md b/userguide/content/en/docs/Updating/Convert-site-to-module.md index e1d46fd6d7..1da5ef035a 100644 --- a/userguide/content/en/docs/Updating/Convert-site-to-module.md +++ b/userguide/content/en/docs/Updating/Convert-site-to-module.md @@ -19,22 +19,9 @@ cat >> config.toml <}} {{< tab header="Windows command line" >}} @@ -45,37 +32,12 @@ hugo mod get github.com/google/docsy [[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 +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 ..\..\..\.. hugo server {{< /tab >}} {{< /tabpane >}} @@ -122,21 +84,6 @@ Next, add the settings given in the code box below at the end of your site confi [[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: @@ -146,17 +93,6 @@ module: 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" >}} { @@ -168,29 +104,7 @@ module: "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" - } - ] + "disable": false } ] } @@ -198,25 +112,68 @@ module: {{< /tab >}} {{< /tabpane >}} - Store the file, and you conversion is done. -### Remove theme and submodule leftovers +### 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-existing-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 +``` + + +### Remove theme and submodule incl. leftovers Since your site makes now use of hugo modules, your previous used themes directory can be removed: ``` -rm -rf /path/to/your/theme/* +rm -rf /path/to/your/theme +``` + +If your docsy theme was installed as submodule, you may remove the themes submodule: + +``` +git rm --cached /path/to/your/submodule/theme +git add . ``` -If your docsy theme was installed as submodule, you may delete the hidden submodule definition file `.gitmodules`, too. +With your submodule deleted, now delete the relevant line form the hidden submodule definition file `.gitmodules`, too. If this is the only line, you can delete the file altogether. ``` rm .gitmodules ``` -Finally, you may clean up the internal directory that git used to store your git submodules: +Finally, you can 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 ``` From f9ab3dabc0aabb71b321f1f5f6df6609c7e71edb Mon Sep 17 00:00:00 2001 From: Andreas Deininger Date: Sat, 15 Jan 2022 22:17:03 +0100 Subject: [PATCH 03/37] Docu for conversion of existing site: improvements and fixes --- .../Docsy-As-Module/start-from-scratch.md | 6 +-- .../docs/Updating/Convert-site-to-module.md | 48 ++++++++++++++++--- 2 files changed, 44 insertions(+), 10 deletions(-) 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 index 1870d1fab4..752c897031 100644 --- 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 @@ -38,12 +38,12 @@ hugo mod get github.com/google/docsy [[module.imports]]^ -path = "github.com/google/docsy")>config.toml +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 ..\..\..\.. +cd ..\..\..\..\.. hugo server {{< /tab >}} {{< /tabpane >}} @@ -66,7 +66,7 @@ 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 +### Import the Docsy theme module as a dependency of 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: diff --git a/userguide/content/en/docs/Updating/Convert-site-to-module.md b/userguide/content/en/docs/Updating/Convert-site-to-module.md index 1da5ef035a..7bfb5168cb 100644 --- a/userguide/content/en/docs/Updating/Convert-site-to-module.md +++ b/userguide/content/en/docs/Updating/Convert-site-to-module.md @@ -15,6 +15,7 @@ At your command prompt, issue: cd /path/to/my-existing-site hugo mod init github.com/me-at-github/my-existing-site hugo mod get github.com/google/docsy +sed -i '/theme = \["docsy"\]/d' config.toml cat >> config.toml < config.toml.temp +move /Y config.toml.temp config.toml (echo [module]^ [[module.imports]]^ -path = "github.com/google/docsy"^)>config.toml +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 ..\..\..\.. +cd ..\..\..\..\.. hugo server {{< /tab >}} {{< /tabpane >}} -## Detailed Setup instructions +## Detailed Conversion instructions -### Add the Docsy theme module to your site +### Import the Docsy theme module as a dependency of your site At the command prompt, change to the root directory of your existing site. @@ -69,9 +72,15 @@ 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 +### Alter the docsy theme definition from local install to Hugo module -Next, add the settings given in the code box below at the end of your site configuration file (default: `config.toml`). +Inside your `config.toml, identify the following line: + +``` +theme = ["docsy"] +``` + +Remove this line and replace it with the settings given in the code box below: {{< tabpane >}} {{< tab header="config.toml" >}} @@ -112,6 +121,31 @@ module: {{< /tab >}} {{< /tabpane >}} +### Check validity of your configuration settings + +To make sure that your configuration settings are correct, issue 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/deining/docsy@v0.0.0-20220114173756-13dd72fd59ba +github.com/google/docsy@v0.0.0-20220114173756-13dd72fd59ba github.com/twbs/bootstrap@v4.6.1+incompatible +github.com/google/docsy@v0.0.0-20220114173756-13dd72fd59ba 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/twbs/bootstrap" +``` +{{% /alert %}} ### Work around a known bug in Go's module management @@ -151,7 +185,7 @@ wget -P assets/vendor/bootstrap/scss/vendor https://raw.githubusercontent.com/tw ### Remove theme and submodule incl. leftovers -Since your site makes now use of hugo modules, your previous used themes directory can be removed: +Since your site makes now use of hugo modules, your previously used `themes` directory can be removed: ``` rm -rf /path/to/your/theme From 444c3f430dc1852f00f004fa8430340ebb7d1d26 Mon Sep 17 00:00:00 2001 From: Andreas Deininger Date: Sun, 30 Jan 2022 20:14:23 +0100 Subject: [PATCH 04/37] User guide: reflect latest changes in hugo module implementation --- userguide/.gitignore | 2 + .../docs/Adding content/Shortcodes/index.md | 6 +- .../content/en/docs/Deployment/_index.md | 2 +- .../example-site-as-template.md | 10 +- .../installation-prerequisites.md | 10 +- .../Docsy-As-Module/start-from-scratch.md | 82 ++++++---------- .../quickstart-clone-git-repo.md | 4 +- .../docs/Updating/Convert-site-to-module.md | 96 ++++++++----------- .../en/docs/Updating/Updating-hugo-module.md | 9 +- 9 files changed, 95 insertions(+), 126 deletions(-) diff --git a/userguide/.gitignore b/userguide/.gitignore index a1b6687b10..82a8734b63 100644 --- a/userguide/.gitignore +++ b/userguide/.gitignore @@ -2,3 +2,5 @@ .hugo_build.lock /public resources/ +# Themes +themes/ \ No newline at end of file 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 >}} -
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. +
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 ead5654a17..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.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" %}} 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 index 8ad7493963..09c6252472 100644 --- 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 @@ -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 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 index 801e04e3e1..bdcf3d4b51 100644 --- 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 @@ -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. 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 index 752c897031..28b55af1e2 100644 --- 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 @@ -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 <}} {{< 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: diff --git a/userguide/content/en/docs/Theme installation/quickstart-clone-git-repo.md b/userguide/content/en/docs/Theme installation/quickstart-clone-git-repo.md index 78c632c75e..0672a0f94a 100644 --- a/userguide/content/en/docs/Theme installation/quickstart-clone-git-repo.md +++ b/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 diff --git a/userguide/content/en/docs/Updating/Convert-site-to-module.md b/userguide/content/en/docs/Updating/Convert-site-to-module.md index 7bfb5168cb..b9f0bdd7bb 100644 --- a/userguide/content/en/docs/Updating/Convert-site-to-module.md +++ b/userguide/content/en/docs/Updating/Convert-site-to-module.md @@ -14,33 +14,34 @@ At your command prompt, issue: {{< 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 +hugo mod get github.com/google/docsy@v0.2.0-pre +hugo mod get github.com/google/docsy/module@v0.2.0-pre sed -i '/theme = \["docsy"\]/d' config.toml 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 +hugo mod get github.com/google/docsy@v0.2.0-pre +hugo mod get github.com/google/docsy/module@v0.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"^)>>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")>>config.toml hugo server {{< /tab >}} {{< /tabpane >}} @@ -62,12 +63,13 @@ Only sites that are hugo modules themselves can import other hugo modules. So tu 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. +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`. @@ -80,7 +82,13 @@ Inside your `config.toml, identify the following line: theme = ["docsy"] ``` -Remove this line and replace it with the settings given in the code box below: +Change this line to: + +``` +theme = ["github.com/google/docsy", "github.com/google/docsy/module"] +``` + +Alternatively, you may this line altogether and replace it with the settings given in the code box below: {{< tabpane >}} {{< tab header="config.toml" >}} @@ -89,31 +97,41 @@ Remove this line and replace it with the settings given in the code box below: # 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 } ] } @@ -128,9 +146,10 @@ To make sure that your configuration settings are correct, issue the command `hu ``` hugo mod graph hugo: collected modules in 1092 ms -github.com/me/my-existing-site github.com/deining/docsy@v0.0.0-20220114173756-13dd72fd59ba -github.com/google/docsy@v0.0.0-20220114173756-13dd72fd59ba github.com/twbs/bootstrap@v4.6.1+incompatible -github.com/google/docsy@v0.0.0-20220114173756-13dd72fd59ba github.com/FortAwesome/Font-Awesome@v0.0.0-20210804190922-7d3d774145ac +github.com/me/my-existing-site github.com/google/docsy@v0.2.0-pre +github.com/me/my-existing-site github.com/google/docsy/module@v0.2.0-pre +github.com/google/docsy/module@v0.2.0-pre github.com/twbs/bootstrap@v4.6.1+incompatible +github.com/google/docsy/module@v0.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. @@ -143,46 +162,11 @@ 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/module" hugo: cleaned module cache for "github.com/twbs/bootstrap" ``` {{% /alert %}} -### 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-existing-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 -``` - - ### Remove theme and submodule incl. leftovers Since your site makes now use of hugo modules, your previously used `themes` directory can be removed: diff --git a/userguide/content/en/docs/Updating/Updating-hugo-module.md b/userguide/content/en/docs/Updating/Updating-hugo-module.md index 76a794ea9d..0d6055225f 100644 --- a/userguide/content/en/docs/Updating/Updating-hugo-module.md +++ b/userguide/content/en/docs/Updating/Updating-hugo-module.md @@ -24,7 +24,14 @@ Hugo will automatically pull in the latest theme version. That's it, your update {{% 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: +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: _v0.2.0_) when updating your theme: + +``` +hugo mod get -u github.com/google/docsy@v0.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 From 9f7000e8f609c13b0cc00413bfc25283aaf9b841 Mon Sep 17 00:00:00 2001 From: Andreas Deininger Date: Wed, 2 Feb 2022 21:57:48 +0100 Subject: [PATCH 05/37] Add warning about order of sections [language] and [module] in config.toml --- userguide/content/en/docs/Language/_index.md | 4 ++++ .../Theme installation/Docsy-As-Module/start-from-scratch.md | 2 +- userguide/content/en/docs/Updating/Convert-site-to-module.md | 4 ++++ 3 files changed, 9 insertions(+), 1 deletion(-) 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/start-from-scratch.md b/userguide/content/en/docs/Theme installation/Docsy-As-Module/start-from-scratch.md index 28b55af1e2..388d5acfd4 100644 --- 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 @@ -155,7 +155,7 @@ You may get Hugo errors for missing parameters and values when you try to build ## 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. +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.**. Please 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: diff --git a/userguide/content/en/docs/Updating/Convert-site-to-module.md b/userguide/content/en/docs/Updating/Convert-site-to-module.md index b9f0bdd7bb..d9ec119d6e 100644 --- a/userguide/content/en/docs/Updating/Convert-site-to-module.md +++ b/userguide/content/en/docs/Updating/Convert-site-to-module.md @@ -139,6 +139,10 @@ module: {{< /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, issue the command `hugo mod graph` which prints a module dependency graph: From e544e540c7e111fde25a3fe84807433ddd212030 Mon Sep 17 00:00:00 2001 From: Andreas Deininger Date: Sun, 6 Feb 2022 17:35:48 +0100 Subject: [PATCH 06/37] Update docu to reflect changes made in e444964a013. --- package.json | 2 +- .../Docsy-As-Module/start-from-scratch.md | 20 +++++++------- .../docs/Updating/Convert-site-to-module.md | 26 +++++++++---------- 3 files changed, 24 insertions(+), 24 deletions(-) diff --git a/package.json b/package.json index f0e8740ed3..75d572a89f 100644 --- a/package.json +++ b/package.json @@ -17,6 +17,6 @@ "bootstrap": "^4.6.1" }, "devDependencies": { - "hugo-extended": "0.93.2" + "hugo-extended": "0.94.0" } } 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 index 388d5acfd4..2261e77985 100644 --- 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 @@ -20,13 +20,13 @@ 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@v0.2.0-pre -hugo mod get github.com/google/docsy/module@v0.2.0-pre +hugo mod get github.com/google/docsy/dependencies@v0.2.0-pre cat >> config.toml <}} @@ -35,7 +35,7 @@ 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@v0.2.0-pre -hugo mod get github.com/google/docsy/module@v0.2.0-pre +hugo mod get github.com/google/docsy/dependencies@v0.2.0-pre (echo [module]^ [[module.imports]]^ @@ -44,7 +44,7 @@ path = "github.com/google/docsy"^ [[module.imports]]^ -path = "github.com/google/docsy/module")>>config.toml +path = "github.com/google/docsy/dependencies")>>config.toml hugo server {{< /tab >}} {{< /tabpane >}} @@ -77,14 +77,14 @@ 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 holds the checksums for module verification. -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`. +Afterwards, declare the docsy theme module as a dependency for your site. Also declare the submodule `dependencies` 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@v0.2.0-pre -hugo mod get github.com/google/docsy/module@v0.2.0-pre +hugo mod get github.com/google/docsy/dependencies@v0.2.0-pre ``` -These commands will add both the docsy theme module and the submodule to your definition file `go.mod`. +These commands will add both the `docsy` theme module and the `dependencies` submodule to your definition file `go.mod`. ### Add theme module configuration settings @@ -102,7 +102,7 @@ Next, add the settings given in the code box below at the end of your site confi path = "github.com/google/docsy" disable = false [[module.imports]] - path = "github.com/google/docsy/module" + path = "github.com/google/docsy/dependencies" disable = false {{< /tab >}} {{< tab header="config.yaml" >}} @@ -114,7 +114,7 @@ module: - path: github.com/google/docsy disable: false imports: - - path: github.com/google/docsy/module + - path: github.com/google/docsy/dependencies disable: false {{< /tab >}} {{< tab header="config.json" >}} @@ -130,7 +130,7 @@ module: "disable": false }, { - "path": "github.com/google/docsy/module", + "path": "github.com/google/docsy/dependencies", "disable": false } ] diff --git a/userguide/content/en/docs/Updating/Convert-site-to-module.md b/userguide/content/en/docs/Updating/Convert-site-to-module.md index d9ec119d6e..9d4b907486 100644 --- a/userguide/content/en/docs/Updating/Convert-site-to-module.md +++ b/userguide/content/en/docs/Updating/Convert-site-to-module.md @@ -15,7 +15,7 @@ At your command prompt, issue: cd /path/to/my-existing-site hugo mod init github.com/me-at-github/my-existing-site hugo mod get github.com/google/docsy@v0.2.0-pre -hugo mod get github.com/google/docsy/module@v0.2.0-pre +hugo mod get github.com/google/docsy/dependencies@v0.2.0-pre sed -i '/theme = \["docsy"\]/d' config.toml cat >> config.toml < config.toml.temp move /Y config.toml.temp config.toml (echo [module]^ @@ -65,14 +65,14 @@ 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 holds the checksums for module verification. -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`. +Afterwards, declare the docsy theme module as a dependency for your site. Also declare the submodule `dependencies` 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@v0.2.0-pre -hugo mod get github.com/google/docsy/module@v0.2.0-pre +hugo mod get github.com/google/docsy/dependencies@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 `dependencies` submodule to your definition file `go.mod`. ### Alter the docsy theme definition from local install to Hugo module @@ -85,7 +85,7 @@ theme = ["docsy"] Change this line to: ``` -theme = ["github.com/google/docsy", "github.com/google/docsy/module"] +theme = ["github.com/google/docsy", "github.com/google/docsy/dependencies"] ``` Alternatively, you may this line altogether and replace it with the settings given in the code box below: @@ -102,7 +102,7 @@ Alternatively, you may this line altogether and replace it with the settings giv path = "github.com/google/docsy" disable = false [[module.imports]] - path = "github.com/google/docsy/module" + path = "github.com/google/docsy/dependencies" disable = false {{< /tab >}} {{< tab header="config.yaml" >}} @@ -114,7 +114,7 @@ module: - path: github.com/google/docsy disable: false imports: - - path: github.com/google/docsy/module + - path: github.com/google/docsy/dependencies disable: false {{< /tab >}} {{< tab header="config.json" >}} @@ -130,7 +130,7 @@ module: "disable": false }, { - "path": "github.com/google/docsy/module", + "path": "github.com/google/docsy/dependencies", "disable": false } ] @@ -151,9 +151,9 @@ To make sure that your configuration settings are correct, issue the command `hu hugo mod graph hugo: collected modules in 1092 ms github.com/me/my-existing-site github.com/google/docsy@v0.2.0-pre -github.com/me/my-existing-site github.com/google/docsy/module@v0.2.0-pre -github.com/google/docsy/module@v0.2.0-pre github.com/twbs/bootstrap@v4.6.1+incompatible -github.com/google/docsy/module@v0.2.0-pre github.com/FortAwesome/Font-Awesome@v0.0.0-20210804190922-7d3d774145ac +github.com/me/my-existing-site github.com/google/docsy/dependencies@v0.2.0-pre +github.com/google/docsy/dependencies@v0.2.0-pre github.com/twbs/bootstrap@v4.6.1+incompatible +github.com/google/docsy/dependencies@v0.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. @@ -166,7 +166,7 @@ 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/module" +hugo: cleaned module cache for "github.com/google/docsy/dependencies" hugo: cleaned module cache for "github.com/twbs/bootstrap" ``` {{% /alert %}} From 3c30707b95d885bc4a8b064bfc7954150791d218 Mon Sep 17 00:00:00 2001 From: LisaFC Date: Wed, 30 Mar 2022 16:48:47 +0100 Subject: [PATCH 07/37] Update _index.md --- .../en/docs/Theme installation/_index.md | 29 +++++++++++++++---- 1 file changed, 23 insertions(+), 6 deletions(-) diff --git a/userguide/content/en/docs/Theme installation/_index.md b/userguide/content/en/docs/Theme installation/_index.md index e4831311c7..f0ce56a966 100644 --- a/userguide/content/en/docs/Theme installation/_index.md +++ b/userguide/content/en/docs/Theme installation/_index.md @@ -1,14 +1,31 @@ --- -title: "Theme Installation" -linkTitle: "Theme Installation" +title: "Get started" +linkTitle: "Get started" weight: 2 date: 2018-07-30 description: > - This page tells about the three different ways to install and make use of the Docsy theme. + Learn how to get started with Docsy, including the available options for installing and using the Docsy theme. --- -### Three Options To Install 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. -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. +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 its 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. Your site uses the modules mechanism to refer to the theme files in 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. +* **Adding the theme as a Git submodule**: Adding the theme as a Git submodule also lets you refer to the theme files in 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. From 38d8ce565588731eefbc898ec2f82c0ca2737681 Mon Sep 17 00:00:00 2001 From: LisaFC Date: Wed, 30 Mar 2022 17:24:34 +0100 Subject: [PATCH 08/37] Update _index.md --- .../Theme installation/Docsy-As-Module/_index.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) 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 index c8475a4420..effd524a51 100644 --- a/userguide/content/en/docs/Theme installation/Docsy-As-Module/_index.md +++ b/userguide/content/en/docs/Theme installation/Docsy-As-Module/_index.md @@ -1,12 +1,16 @@ --- -title: "Option 1: Making use of Docsy Theme as Hugo Module (Modern)" -linkTitle: "Docsy as Hugo Module" +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: > - Instructions on modern installation of the Docsy theme as hugo module which is automatically pulled in. + Learn how to get started with Docsy by using the theme as a Hugo Module. --- -### Two Routes To Built Your Site +[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. -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. +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 + +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. From 72b08cd09ba7232259d73f91eeac78ad308350e7 Mon Sep 17 00:00:00 2001 From: LisaFC Date: Wed, 30 Mar 2022 17:42:43 +0100 Subject: [PATCH 09/37] Update installation-prerequisites.md --- .../installation-prerequisites.md | 37 +++++++++---------- 1 file changed, 18 insertions(+), 19 deletions(-) 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 index bdcf3d4b51..95b0708ca2 100644 --- 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 @@ -1,21 +1,21 @@ --- -title: "Pre-Installation of Prerequisites" -linkTitle: "Installation of Prerequisites" +title: "Before you begin" +linkTitle: "Before you begin" 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 for building a site with Docsy as a Hugo Module. --- -## Prerequisites and installation +This page describes the prerequisites for building a site that uses Docsy as a Hugo Module. -### Install Hugo +## 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/). -#### Linux +### 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. @@ -44,11 +44,11 @@ If the result is `v0.73` or earlier, or if you don't see `Extended`, you'll need sudo install hugo /usr/bin -#### macOS +### On macOS Install Hugo using [Brew](https://gohugo.io/getting-started/installing/#homebrew-macos). -#### As an `npm` module +### 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: @@ -58,33 +58,32 @@ npm install hugo-extended --save-dev See the [`hugo-bin` documentation](https://www.npmjs.com/package/hugo-bin) for usage details. -### Install Go language +## 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: +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 ``` -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. +Ensure that you are using version 1.12 or higher. -{{% alert title="Warning" color="warning" %}} -Make sure you are using go version 1.12 or higher, otherwise you might run in trouble. -{{% /alert %}} +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: +## 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, 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. +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 +## 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): @@ -103,7 +102,7 @@ Note that versions of `PostCSS` later than 5.0.1 will not load `autoprefixer` if ## What's next? -With all prerequisites installed, you now have to select how to start off with your new hugo site +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/) From 97147bd603e4389ee4c73d9ce58c32e212dfb4d8 Mon Sep 17 00:00:00 2001 From: LisaFC Date: Wed, 30 Mar 2022 17:46:35 +0100 Subject: [PATCH 10/37] Update _index.md --- userguide/content/en/docs/Theme installation/_index.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/userguide/content/en/docs/Theme installation/_index.md b/userguide/content/en/docs/Theme installation/_index.md index f0ce56a966..96a0ddcfa0 100644 --- a/userguide/content/en/docs/Theme installation/_index.md +++ b/userguide/content/en/docs/Theme installation/_index.md @@ -10,7 +10,7 @@ description: > 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 its dependencies, or by using our provided Docker container. +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. @@ -18,14 +18,14 @@ This page describes Docsy's installation options and helps you choose the approp 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. Your site uses the modules mechanism to refer to the theme files in 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. -* **Adding the theme as a Git submodule**: Adding the theme as a Git submodule also lets you refer to the theme files in 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. +* **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. +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. +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. From 110f7c3551c94e438cdb9a06c272400c6078fce2 Mon Sep 17 00:00:00 2001 From: LisaFC Date: Wed, 30 Mar 2022 18:21:23 +0100 Subject: [PATCH 11/37] Update example-site-as-template.md --- .../example-site-as-template.md | 34 +++++++++---------- 1 file changed, 17 insertions(+), 17 deletions(-) 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 index 09c6252472..36853777a7 100644 --- 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 @@ -1,17 +1,19 @@ --- -title: "Route 1: Start with a clone of the prepopulated Docsy example site (for beginners)" +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: > - Start off with your new hugo site using a clone of the prepopulated Docsy example site theme as starting point. + Create a new Hugo site by using a clone of the Docsy example site as your 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/). +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 your Windows command line, issue: +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 @@ -19,30 +21,28 @@ cd my-new-site hugo server ``` -You now can preview your new site inside your browser at [http://localhost:1313](http://localhost:1313/). +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 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. +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: -* [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) +* 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. -#### Route 1: Using the command line (local site repo only) +#### Option 1: Using the command line (local copy 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 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`): +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 ``` -#### Route 2: Using the GitHub UI (local site repo + associated remote GitHub repo) +#### 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: @@ -50,9 +50,9 @@ As the Docsy example site repo is a [template repository](https://github.blog/20 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. 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, using git's `clone` subcommand, give your repo's web URL as last parameter. +1. Make a local copy of your newly created GitHub repository by using `git clone`, giving your repo's web URL as last parameter. 
     git clone https://github.com/me-at-github/my-new-site.git
@@ -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 hugo's `server` subcommand::
+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

From 042dd7b6e37dbc1fa31c3b64685ded8050667d2b Mon Sep 17 00:00:00 2001
From: LisaFC 
Date: Wed, 30 Mar 2022 18:59:01 +0100
Subject: [PATCH 12/37] Update start-from-scratch.md

---
 .../Docsy-As-Module/start-from-scratch.md     | 29 +++++++++----------
 1 file changed, 13 insertions(+), 16 deletions(-)

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
index 2261e77985..0fa48f1606 100644
--- 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	
@@ -1,18 +1,17 @@
 ---
-title: "Route 2: Start your new hugo site from scratch (for experts)"
-linkTitle: "Start site from scratch (experts)"
+title: "Create a new site: Start a new site from scratch"
+linkTitle: "Start site from scratch"
 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.
+  Create a new Hugo site from scratch with Docsy as a Hugo Module
 ---
 
-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.
-
+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. This approach gives you a minimum skeleton 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, issue:
+At your command prompt, run the following:
 
 {{< tabpane >}}
 {{< tab header="Unix shell" >}}
@@ -54,9 +53,9 @@ You now can preview your new site inside your browser at [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.
+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
+### 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.
 
@@ -69,26 +68,26 @@ This will create a minimal site structure, containing the folders `archetypes`,
 
 ### Import the Docsy theme module as a dependency of 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:
+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 will create two new files, `go.mod` for the module definitions and `go.sum` which holds the checksums for module verification.
+This creates two new files, `go.mod` for the module definitions and `go.sum` which holds the checksums for module verification.
 
-Afterwards, declare the docsy theme module as a dependency for your site. Also declare the submodule `dependencies` 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`.
+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@v0.2.0-pre
 hugo mod get github.com/google/docsy/dependencies@v0.2.0-pre
 ```
 
-These commands will add both the `docsy` theme module and the `dependencies` submodule to your definition file `go.mod`.
+These commands add both the `docsy` theme module and the `dependencies` submodule 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`).
+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" >}}
@@ -139,8 +138,6 @@ module:
 {{< /tab >}}
 {{< /tabpane >}}
 
- Store the file, and your site configuration is finished.
-
 ### Preview your site
 
 To build and preview your site locally:
@@ -151,7 +148,7 @@ 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.
+You may get Hugo errors for missing parameters and values when you try to build your site. These errors will go away once you complete basic site configuration as described in the next section.
 
 ## Basic site configuration
 

From 53630b84eb5de8b853ce35314460c3be2fe0eed2 Mon Sep 17 00:00:00 2001
From: LisaFC 
Date: Wed, 30 Mar 2022 19:07:13 +0100
Subject: [PATCH 13/37] Update start-from-scratch.md

---
 .../Theme installation/Docsy-As-Module/start-from-scratch.md    | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

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
index 0fa48f1606..2333e60eda 100644
--- 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	
@@ -1,6 +1,6 @@
 ---
 title: "Create a new site: Start a new site from scratch"
-linkTitle: "Start site from scratch"
+linkTitle: "Start a site from scratch"
 date: 2021-12-08T09:21:54+01:00
 weight: 3
 description: >

From 9d257dc2888c5bc282fb69d099bda0d345a65c95 Mon Sep 17 00:00:00 2001
From: LisaFC 
Date: Wed, 30 Mar 2022 19:21:27 +0100
Subject: [PATCH 14/37] Update and rename quickstart-clone-git-repo.md to
 docsy-as-submodule

---
 ...t-clone-git-repo.md => docsy-as-submodule} | 116 +++---------------
 1 file changed, 14 insertions(+), 102 deletions(-)
 rename userguide/content/en/docs/Theme installation/{quickstart-clone-git-repo.md => docsy-as-submodule} (53%)

diff --git a/userguide/content/en/docs/Theme installation/quickstart-clone-git-repo.md b/userguide/content/en/docs/Theme installation/docsy-as-submodule
similarity index 53%
rename from userguide/content/en/docs/Theme installation/quickstart-clone-git-repo.md
rename to userguide/content/en/docs/Theme installation/docsy-as-submodule
index 0672a0f94a..7fb1e8fdcc 100644
--- a/userguide/content/en/docs/Theme installation/quickstart-clone-git-repo.md	
+++ b/userguide/content/en/docs/Theme installation/docsy-as-submodule	
@@ -1,13 +1,17 @@
 ---
-title: "Option 2: Cloning the Docsy Theme from a GitHub Repo (Traditional)"
-linkTitle: "Cloning GitHub Repo (Traditional)"
+title: "Other setup options"
+linkTitle: "Other setup options"
 date: 2021-12-08T09:22:27+01:00
 weight: 2
 description: >
-  Instructions on traditional installation and basic configuration of the Docsy theme by cloning the Docsy GitHub repo.
+  Create a new Docsy site with Docsy as a Git submodule or cloned theme
 ---
 
-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.
+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
 
@@ -17,7 +21,7 @@ You need a [recent **extended** version](https://github.com/gohugoio/hugo/releas
 
 For comprehensive Hugo documentation, see [gohugo.io](https://gohugo.io/).
 
-#### Linux
+#### 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.
 
@@ -46,7 +50,7 @@ If the result is `v0.73` or earlier, or if you don't see `Extended`, you'll need
 
         sudo install hugo /usr/bin    
 
-#### macOS
+#### On macOS
 
 Install Hugo using [Brew](https://gohugo.io/getting-started/installing/#homebrew-macos).
 
@@ -77,101 +81,9 @@ 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):
-
-    
-    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](/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
-
-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).
-
+## Use the theme as a submodule
 
-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 Docsy theme as a submodule, run the following commands from your project's root directory.
 
 ```shell
 hugo new site myproject
@@ -190,7 +102,7 @@ echo 'theme = "docsy"' >> config.toml
 git submodule update --init --recursive
 ```
 
-#### Cloning the Docsy theme to your project's `themes` subdirectory
+## Clone 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.
 
@@ -212,7 +124,7 @@ 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
+## Preview your site
 
 To build and preview your site locally:
 

From 38d503b4a82e7563038741c576eb25a2726e36d2 Mon Sep 17 00:00:00 2001
From: LisaFC 
Date: Wed, 30 Mar 2022 19:23:59 +0100
Subject: [PATCH 15/37] Update _index.md

---
 .../en/docs/Theme installation/Docsy-As-Module/_index.md     | 5 +++++
 1 file changed, 5 insertions(+)

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
index effd524a51..dc68918ca0 100644
--- a/userguide/content/en/docs/Theme installation/Docsy-As-Module/_index.md	
+++ b/userguide/content/en/docs/Theme installation/Docsy-As-Module/_index.md	
@@ -13,4 +13,9 @@ To find out about other setup approaches, see our [Get started](/docs/get-starte
 
 ## 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.

From 6e5384ffa92056867c9533093d55b45eacd0bae6 Mon Sep 17 00:00:00 2001
From: LisaFC 
Date: Wed, 30 Mar 2022 19:25:11 +0100
Subject: [PATCH 16/37] Update start-from-scratch.md

---
 .../Theme installation/Docsy-As-Module/start-from-scratch.md  | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

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
index 2333e60eda..31b0bc6efa 100644
--- 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	
@@ -7,7 +7,9 @@ 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. This approach gives you a minimum skeleton 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.
+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
 

From 4635197593e44fbcf6d826339bc0269014cc7239 Mon Sep 17 00:00:00 2001
From: LisaFC 
Date: Wed, 30 Mar 2022 19:26:12 +0100
Subject: [PATCH 17/37] Rename docsy-as-submodule to other-options

---
 .../docs/Theme installation/{docsy-as-submodule => other-options} | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename userguide/content/en/docs/Theme installation/{docsy-as-submodule => other-options} (100%)

diff --git a/userguide/content/en/docs/Theme installation/docsy-as-submodule b/userguide/content/en/docs/Theme installation/other-options
similarity index 100%
rename from userguide/content/en/docs/Theme installation/docsy-as-submodule
rename to userguide/content/en/docs/Theme installation/other-options

From c97a1b8fb074d153a90db16ac77d2fd8046007ac Mon Sep 17 00:00:00 2001
From: LisaFC 
Date: Wed, 30 Mar 2022 19:27:14 +0100
Subject: [PATCH 18/37] Rename other-options to other-options.md

---
 .../docs/Theme installation/{other-options => other-options.md}   | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename userguide/content/en/docs/Theme installation/{other-options => other-options.md} (100%)

diff --git a/userguide/content/en/docs/Theme installation/other-options b/userguide/content/en/docs/Theme installation/other-options.md
similarity index 100%
rename from userguide/content/en/docs/Theme installation/other-options
rename to userguide/content/en/docs/Theme installation/other-options.md

From 70e29c25d1937ace048aa2b627262bef131c2379 Mon Sep 17 00:00:00 2001
From: LisaFC 
Date: Thu, 31 Mar 2022 13:03:03 +0100
Subject: [PATCH 19/37] Create basic-configuration.md

---
 .../Theme installation/basic-configuration.md | 54 +++++++++++++++++++
 1 file changed, 54 insertions(+)
 create mode 100644 userguide/content/en/docs/Theme installation/basic-configuration.md

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..601138560a
--- /dev/null
+++ b/userguide/content/en/docs/Theme installation/basic-configuration.md	
@@ -0,0 +1,54 @@
+---
+title: "Basic configuration"
+linkTitle: "Basic 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/).

From a61f806be4d68f6dbc0c7e0613e8eb32c59265ea Mon Sep 17 00:00:00 2001
From: LisaFC 
Date: Thu, 31 Mar 2022 13:13:05 +0100
Subject: [PATCH 20/37] Update example-site-as-template.md

---
 .../Docsy-As-Module/example-site-as-template.md                  | 1 +
 1 file changed, 1 insertion(+)

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
index 36853777a7..14fc56dc33 100644
--- 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	
@@ -76,6 +76,7 @@ Use `Ctrl + c` to stop the Hugo server whenever you like.
 
 ## 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/).

From 2e6923436d0525c771ebaf2b660ec5b2e3f3475d Mon Sep 17 00:00:00 2001
From: LisaFC 
Date: Thu, 31 Mar 2022 15:04:22 +0100
Subject: [PATCH 21/37] Update start-from-scratch.md

---
 .../Docsy-As-Module/start-from-scratch.md     | 45 +------------------
 1 file changed, 2 insertions(+), 43 deletions(-)

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
index 31b0bc6efa..e9536bf845 100644
--- 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	
@@ -150,52 +150,11 @@ 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 complete basic site configuration as described in the next section.
-
-## 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.**. Please 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).
-
+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/).

From b905bf6929e9f109ac0fccdd609e11c7913440a8 Mon Sep 17 00:00:00 2001
From: LisaFC 
Date: Thu, 31 Mar 2022 15:08:06 +0100
Subject: [PATCH 22/37] Update other-options.md

---
 .../docs/Theme installation/other-options.md  | 53 ++-----------------
 1 file changed, 5 insertions(+), 48 deletions(-)

diff --git a/userguide/content/en/docs/Theme installation/other-options.md b/userguide/content/en/docs/Theme installation/other-options.md
index 7fb1e8fdcc..93e44ef10e 100644
--- a/userguide/content/en/docs/Theme installation/other-options.md	
+++ b/userguide/content/en/docs/Theme installation/other-options.md	
@@ -81,7 +81,7 @@ 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.
 
-## Use the theme as a submodule
+## 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.
 
@@ -102,12 +102,9 @@ echo 'theme = "docsy"' >> config.toml
 git submodule update --init --recursive
 ```
 
-## Clone 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.
-
-
+## 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:
 
@@ -135,52 +132,12 @@ 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).
+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/).

From 821cc77c67d725d42daae92052c60906a876a628 Mon Sep 17 00:00:00 2001
From: LisaFC 
Date: Thu, 31 Mar 2022 15:10:17 +0100
Subject: [PATCH 23/37] Update basic-configuration.md

---
 .../content/en/docs/Theme installation/basic-configuration.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/userguide/content/en/docs/Theme installation/basic-configuration.md b/userguide/content/en/docs/Theme installation/basic-configuration.md
index 601138560a..19875ea429 100644
--- a/userguide/content/en/docs/Theme installation/basic-configuration.md	
+++ b/userguide/content/en/docs/Theme installation/basic-configuration.md	
@@ -1,6 +1,6 @@
 ---
-title: "Basic configuration"
-linkTitle: "Basic configuration"
+title: "Basic site configuration"
+linkTitle: "Basic site configuration"
 date: 2021-12-08T09:22:27+01:00
 weight: 4
 description: >

From a307f4361d919ab93b8d44350d455d33f8af3fd9 Mon Sep 17 00:00:00 2001
From: LisaFC 
Date: Thu, 31 Mar 2022 15:17:41 +0100
Subject: [PATCH 24/37] Update quickstart-docker.md

---
 .../content/en/docs/Theme installation/quickstart-docker.md     | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/userguide/content/en/docs/Theme installation/quickstart-docker.md b/userguide/content/en/docs/Theme installation/quickstart-docker.md
index f817433105..db3f4d365e 100644
--- a/userguide/content/en/docs/Theme installation/quickstart-docker.md	
+++ b/userguide/content/en/docs/Theme installation/quickstart-docker.md	
@@ -1,6 +1,6 @@
 
 ---
-title: "Option 3: Deploy Docsy inside a Docker container"
+title: "Deploy Docsy inside a Docker container"
 linkTitle: "Deploy Docsy inside a Docker container"
 weight: 3
 date: 2018-07-30

From 1ba2aff42d8697f02e915e06fb26ef1cac75a774 Mon Sep 17 00:00:00 2001
From: LisaFC 
Date: Thu, 31 Mar 2022 15:27:18 +0100
Subject: [PATCH 25/37] Update _index.md

---
 userguide/content/en/docs/Updating/_index.md | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/userguide/content/en/docs/Updating/_index.md b/userguide/content/en/docs/Updating/_index.md
index 7b9ea5ecfe..86d52412a4 100644
--- a/userguide/content/en/docs/Updating/_index.md
+++ b/userguide/content/en/docs/Updating/_index.md
@@ -1,18 +1,19 @@
 ---
-title: "Update of Docsy Theme of conversion of existing site to hugo modules"
-linkTitle: "Update or Conversion of Docsy Theme"
+title: "Updating Docsy"
+linkTitle: "Updating Docsy"
 weight: 8
 description: >
  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. 
 
 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 
-[Docsy commits](https://github.com/google/docsy/commits/main).
\ No newline at end of file
+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).
+
+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.

From 247c28eb84bab77883a42e060b112a48273afcd0 Mon Sep 17 00:00:00 2001
From: LisaFC 
Date: Thu, 31 Mar 2022 15:30:45 +0100
Subject: [PATCH 26/37] Update Updating-hugo-module.md

---
 .../content/en/docs/Updating/Updating-hugo-module.md   | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/userguide/content/en/docs/Updating/Updating-hugo-module.md b/userguide/content/en/docs/Updating/Updating-hugo-module.md
index 0d6055225f..16f9981333 100644
--- a/userguide/content/en/docs/Updating/Updating-hugo-module.md
+++ b/userguide/content/en/docs/Updating/Updating-hugo-module.md
@@ -1,12 +1,12 @@
 ---
-title: "Update of Docsy theme if used as hugo module"
-linkTitle: "Update of Docsy (hugo module)"
+title: "Update the Docsy Hugo Module"
+linkTitle: "Update the Docsy Hugo Module"
 weight: 1
 description: >
-  Updating Docsy theme to latest version (for installations that use Docsy theme as **hugo module**).
+  Update the Docsy theme to the latest version using Hugo Modules.
 ---
 
-When making use of Dosy theme as hugo module, updating your theme is really easy:
+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.
 
@@ -20,7 +20,7 @@ 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!
+Hugo automatically pulls in the latest theme version. That's it, your update is done!
 
 
 {{% alert title="Tip" %}}

From d6f54803d3a9d1e831c506867a27fe76df677140 Mon Sep 17 00:00:00 2001
From: LisaFC 
Date: Thu, 31 Mar 2022 15:36:51 +0100
Subject: [PATCH 27/37] Update _index.md

---
 userguide/content/en/docs/Updating/_index.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/userguide/content/en/docs/Updating/_index.md b/userguide/content/en/docs/Updating/_index.md
index 86d52412a4..00c0e19931 100644
--- a/userguide/content/en/docs/Updating/_index.md
+++ b/userguide/content/en/docs/Updating/_index.md
@@ -1,6 +1,6 @@
 ---
-title: "Updating Docsy"
-linkTitle: "Updating Docsy"
+title: "Update Docsy"
+linkTitle: "Update Docsy"
 weight: 8
 description: >
  Keeping the Docsy theme up to date.

From 68867cac1ffa928cd45bb2f97ae6c652a51d2343 Mon Sep 17 00:00:00 2001
From: LisaFC 
Date: Thu, 31 Mar 2022 15:42:23 +0100
Subject: [PATCH 28/37] Update Updating-submodules.md

---
 .../en/docs/Updating/Updating-submodules.md   | 20 +++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/userguide/content/en/docs/Updating/Updating-submodules.md b/userguide/content/en/docs/Updating/Updating-submodules.md
index 9dcfdb2995..aec183a67c 100644
--- a/userguide/content/en/docs/Updating/Updating-submodules.md
+++ b/userguide/content/en/docs/Updating/Updating-submodules.md
@@ -1,20 +1,20 @@
 ---
-title: "Update of Docsy theme if used traditionally (no hugo module)"
-linkTitle: "Update of Docsy (no module)"
+title: "Update Docsy without Hugo Modules
+linkTitle: "Update Docsy without Hugo Modules"
 weight: 2
 description: >
-  Updating Docsy theme to latest version (for traditional installations **not** using hugo as module).
+  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, 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.
+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 %}}
 
-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
+## 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:
+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:
 
@@ -34,7 +34,7 @@ If you are using the Docsy theme as a submodule in your project (for example, if
 
 ## 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
+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:
@@ -49,4 +49,4 @@ the `themes` folder in your project, then you use the `git pull` command:
 
         git pull origin master
 
-If you have made any local changes to the cloned theme, you must manually resolve any merge conflicts.
+If you have made any local changes to the cloned theme, **you must manually resolve any merge conflicts**.

From c7412387c1e41ad89e3000eac4f7cfb66eed1e97 Mon Sep 17 00:00:00 2001
From: LisaFC 
Date: Thu, 31 Mar 2022 15:47:31 +0100
Subject: [PATCH 29/37] Update _index.md

---
 userguide/content/en/docs/Updating/_index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/userguide/content/en/docs/Updating/_index.md b/userguide/content/en/docs/Updating/_index.md
index 00c0e19931..8ad20f162b 100644
--- a/userguide/content/en/docs/Updating/_index.md
+++ b/userguide/content/en/docs/Updating/_index.md
@@ -7,7 +7,7 @@ description: >
 ---
 
 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 Hugo Module or Git submodule), you can easily update the Docsy theme in your site 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 

From 091485cdc7484c7aca74030a626d9d9bbdbbd681 Mon Sep 17 00:00:00 2001
From: LisaFC 
Date: Thu, 31 Mar 2022 16:16:05 +0100
Subject: [PATCH 30/37] Update Convert-site-to-module.md

---
 .../docs/Updating/Convert-site-to-module.md   | 36 +++++++++----------
 1 file changed, 18 insertions(+), 18 deletions(-)

diff --git a/userguide/content/en/docs/Updating/Convert-site-to-module.md b/userguide/content/en/docs/Updating/Convert-site-to-module.md
index 9d4b907486..d203268855 100644
--- a/userguide/content/en/docs/Updating/Convert-site-to-module.md
+++ b/userguide/content/en/docs/Updating/Convert-site-to-module.md
@@ -1,14 +1,14 @@
 ---
-title: "Convert an existing site to Docsy hugo module"
-linkTitle: "Convert existing site to Docsy hugo module"
+title: "Migrate to Hugo Modules"
+linkTitle: "Migrate to Hugo Modules"
 weight: 3
 description: >
-  Convert an existing site, turning Hugo Docsy theme into a hugo module.
+  Convert an existing site to use Docsy as a Hugo Module
 ---
 
 ## TL;DR: Conversion for the impatient expert
 
-At your command prompt, issue:
+Run the following from the command line:
 
 {{< tabpane >}}
 {{< tab header="Unix shell" >}}
@@ -47,7 +47,7 @@ hugo server
 {{< /tabpane >}}
 
 
-## Detailed Conversion instructions
+## Detailed conversion instructions
 
 ### Import the Docsy theme module as a dependency of your site
 
@@ -57,26 +57,26 @@ 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:
+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 will create two new files, `go.mod` for the module definitions and `go.sum` which holds the checksums for module verification.
+This creates two new files, `go.mod` for the module definitions and `go.sum` which holds the checksums for module verification.
 
-Afterwards, declare the docsy theme module as a dependency for your site. Also declare the submodule `dependencies` 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`.
+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@v0.2.0-pre
 hugo mod get github.com/google/docsy/dependencies@v0.2.0-pre
 ```
 
-These commands will add both the `docsy` theme module and the `dependencies` submodule to your definition file `go.mod`.
+These commands add both the `docsy` theme module and the `dependencies` submodule to your definition file `go.mod`.
 
-### Alter the docsy theme definition from local install to Hugo module
+### Update your config file
 
-Inside your `config.toml, identify the following line:
+In your `config.toml` file, update the theme setting to use Hugo Modules. Find the following line:
 
 ```
 theme = ["docsy"]
@@ -88,7 +88,7 @@ Change this line to:
 theme = ["github.com/google/docsy", "github.com/google/docsy/dependencies"]
 ```
 
-Alternatively, you may this line altogether and replace it with the settings given in the code box below:
+Alternatively, you can omit this line altogether and replace it with the settings given in the following snippet:
 
 {{< tabpane >}}
 {{< tab header="config.toml" >}}
@@ -145,7 +145,7 @@ If you have a multi language installation, please make sure that the section `[l
 
 ### Check validity of your configuration settings
 
-To make sure that your configuration settings are correct, issue the command `hugo mod graph` which prints a module dependency graph:
+To make sure that your configuration settings are correct, run the command `hugo mod graph` which prints a module dependency graph:
 
 ```
 hugo mod graph
@@ -171,28 +171,28 @@ hugo: cleaned module cache for "github.com/twbs/bootstrap"
 ```
 {{% /alert %}}
 
-### Remove theme and submodule incl. leftovers
+### Clean up your repository
 
-Since your site makes now use of hugo modules, your previously used `themes` directory can be removed: 
+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 may remove the themes submodule:
+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 form the hidden submodule definition file `.gitmodules`, too. If this is the only line, you can delete the file altogether.
+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, you can delete the now untracked submodule files and also clean up the internal directory that git used to store your git submodules:
+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

From ef11399a4d5f8394534d7d66acacba86d026d527 Mon Sep 17 00:00:00 2001
From: LisaFC 
Date: Thu, 31 Mar 2022 16:27:06 +0100
Subject: [PATCH 31/37] Update Updating-submodules.md

---
 userguide/content/en/docs/Updating/Updating-submodules.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/userguide/content/en/docs/Updating/Updating-submodules.md b/userguide/content/en/docs/Updating/Updating-submodules.md
index aec183a67c..8fff012cf5 100644
--- a/userguide/content/en/docs/Updating/Updating-submodules.md
+++ b/userguide/content/en/docs/Updating/Updating-submodules.md
@@ -3,7 +3,7 @@ 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`
+  Update the Docsy theme to the latest version using submodules or a cloned theme.
 ---
 
 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.

From 4bab4b5412e8eddf6b8fcdb9e0d05ea0da11e325 Mon Sep 17 00:00:00 2001
From: LisaFC 
Date: Thu, 31 Mar 2022 16:38:51 +0100
Subject: [PATCH 32/37] Update Updating-submodules.md

---
 userguide/content/en/docs/Updating/Updating-submodules.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/userguide/content/en/docs/Updating/Updating-submodules.md b/userguide/content/en/docs/Updating/Updating-submodules.md
index 8fff012cf5..f29aa01641 100644
--- a/userguide/content/en/docs/Updating/Updating-submodules.md
+++ b/userguide/content/en/docs/Updating/Updating-submodules.md
@@ -1,9 +1,9 @@
 ---
-title: "Update Docsy without Hugo Modules
+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 a cloned theme.
+  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.

From 6c49bca9d3c07f61e879c0985644dad070fd83e1 Mon Sep 17 00:00:00 2001
From: Andreas Deininger 
Date: Thu, 31 Mar 2022 16:53:59 +0200
Subject: [PATCH 33/37] Correct links to pre-release version 0.2.0-pre

---
 netlify.toml                                  |  2 +-
 package.json                                  |  2 +-
 .../Docsy-As-Module/start-from-scratch.md     | 12 +++++------
 .../docs/Updating/Convert-site-to-module.md   | 20 +++++++++----------
 .../en/docs/Updating/Updating-hugo-module.md  |  4 ++--
 5 files changed, 20 insertions(+), 20 deletions(-)

diff --git a/netlify.toml b/netlify.toml
index 0f24ebcc06..fc72cc254f 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.0"
 HUGO_THEME = "repo"
 
 [context.production]
diff --git a/package.json b/package.json
index 75d572a89f..17c6d23c09 100644
--- a/package.json
+++ b/package.json
@@ -17,6 +17,6 @@
     "bootstrap": "^4.6.1"
   },
   "devDependencies": {
-    "hugo-extended": "0.94.0"
+    "hugo-extended": "0.96.0"
   }
 }
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
index e9536bf845..09302ed620 100644
--- 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	
@@ -20,8 +20,8 @@ At your command prompt, run the following:
 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@v0.2.0-pre
-hugo mod get github.com/google/docsy/dependencies@v0.2.0-pre
+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 <}}
 cd /path/to/my-existing-site
 hugo mod init github.com/me-at-github/my-existing-site
-hugo mod get github.com/google/docsy@v0.2.0-pre
-hugo mod get github.com/google/docsy/dependencies@v0.2.0-pre
+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 <}}
 cd  my-existing-site
 hugo mod init github.com/me-at-github/my-existing-site
-hugo mod get github.com/google/docsy@v0.2.0-pre
-hugo mod get github.com/google/docsy/dependencies@v0.2.0-pre
+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]^
@@ -68,8 +68,8 @@ This creates two new files, `go.mod` for the module definitions and `go.sum` whi
 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@v0.2.0-pre
-hugo mod get github.com/google/docsy/dependencies@v0.2.0-pre
+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`.
@@ -150,10 +150,10 @@ To make sure that your configuration settings are correct, run the command `hugo
 ```
 hugo mod graph
 hugo: collected modules in 1092 ms
-github.com/me/my-existing-site github.com/google/docsy@v0.2.0-pre
-github.com/me/my-existing-site github.com/google/docsy/dependencies@v0.2.0-pre
-github.com/google/docsy/dependencies@v0.2.0-pre github.com/twbs/bootstrap@v4.6.1+incompatible
-github.com/google/docsy/dependencies@v0.2.0-pre github.com/FortAwesome/Font-Awesome@v0.0.0-20210804190922-7d3d774145ac
+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.
diff --git a/userguide/content/en/docs/Updating/Updating-hugo-module.md b/userguide/content/en/docs/Updating/Updating-hugo-module.md
index 16f9981333..d72527ee56 100644
--- a/userguide/content/en/docs/Updating/Updating-hugo-module.md
+++ b/userguide/content/en/docs/Updating/Updating-hugo-module.md
@@ -24,10 +24,10 @@ Hugo automatically pulls in the latest theme version. That's it, your update is
 
 
 {{% 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: _v0.2.0_) when updating your theme:
+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@v0.2.0
+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:

From a24f1b2c679d27d6180e590968122765ceff0beb Mon Sep 17 00:00:00 2001
From: Andreas Deininger 
Date: Fri, 1 Apr 2022 09:08:51 +0200
Subject: [PATCH 34/37] Netlify: correcting go version

---
 netlify.toml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/netlify.toml b/netlify.toml
index fc72cc254f..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.18.0"
+GO_VERSION = "1.18"
 HUGO_THEME = "repo"
 
 [context.production]

From 98ee40565fca860ac391a3a61487087eb5f84be0 Mon Sep 17 00:00:00 2001
From: LisaFC 
Date: Fri, 1 Apr 2022 16:15:04 +0100
Subject: [PATCH 35/37] Compactify menu

...as left nav is getting very big...
---
 userguide/config.toml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

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.

From f96edf2c5ebd990d18eea7b0a0ed8d235d6a5610 Mon Sep 17 00:00:00 2001
From: LisaFC 
Date: Fri, 1 Apr 2022 16:26:55 +0100
Subject: [PATCH 36/37] Fixed broken link to setup guide

---
 userguide/content/en/docs/_index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

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!
 
 

From 71641a420db4853e9fb816c7de5bec3f332fef07 Mon Sep 17 00:00:00 2001
From: Andreas Deininger 
Date: Sun, 3 Apr 2022 10:04:32 +0200
Subject: [PATCH 37/37] User guide, .gitignore: remove unneeded entry

---
 userguide/.gitignore | 2 --
 1 file changed, 2 deletions(-)

diff --git a/userguide/.gitignore b/userguide/.gitignore
index 82a8734b63..a1b6687b10 100644
--- a/userguide/.gitignore
+++ b/userguide/.gitignore
@@ -2,5 +2,3 @@
 .hugo_build.lock
 /public
 resources/
-# Themes
-themes/
\ No newline at end of file