📝 Add extra clarity to upgrade docs

exampleSite/content/docs/configuration.md

@@ -89,6 +89,14 @@ The default file can be used as a template to create additional languages, or re
 |`author.links`|_Not set_|The links to display alongside the author's details. The config file contains example links which can simply be uncommented to enable. The order that the links are displayed is determined by the order they appear in the array. Custom links can be added by providing corresponding SVG icon assets in `assets/icons/`.|
 <!-- prettier-ignore-end -->
 
+### Menus
+
+Congo also supports language-specific menu configurations. Menu config files follow the same naming format as the languages file. Simply provide the language code in the file name to tell Hugo which language the file relates to.
+
+Menu config files are named with the format `menus.[language-code].toml`. Always ensure that the language code used in the menus configuration matches the languages configuration.
+
+The [Getting Started]({{< ref "getting-started#menus" >}}) section explains more about the structure of this file. You can also refer to the [Hugo menu docs](https://gohugo.io/content-management/menus/) for more configuration examples.
+
 ## Theme parameters
 
 Congo provides a large number of configuration parameters that control how the theme functions. The table below outlines every available parameter in the `config/_default/params.toml` file.

exampleSite/content/docs/getting-started.md

@@ -131,7 +131,7 @@ When you create a new taxonomy, you will need to adjust the navigation links on
 
 Congo has two menus that can be customised to suit the content and layout of your site. The `main` menu appears in the site header and the `footer` menu appears at the bottom of the page just above the copyright notice.
 
-Both menus are configured in the `menus.toml` file.
+Both menus are configured in the `menus.en.toml` file. Similarly to the languages config file, if you wish to use another language, rename this file and replace `en` with the language code you wish to use.
 
 ```toml
 # config/_default/menus.toml

exampleSite/content/docs/version-2/upgrade/index.md

@@ -38,6 +38,8 @@ Then change into your project directory and execute the following command:
 hugo mod get -u
 ```
 
+Note that in some circumstances there may be issues with this step due to the way that Hugo locally caches modules. If the command above doesn't work, try using `hugo mod clean` to clear out the local cache and re-download any modules.
+
 Once the theme has been upgraded, continue to the [next section](#step-3-theme-configuration).
 
 ### Upgrade using git
@@ -45,7 +47,7 @@ Once the theme has been upgraded, continue to the [next section](#step-3-theme-c
 Git submodules can be upgraded using the `git` command. Simply execute the following command and the latest version of the theme will be downloaded into your local repository:
 
 ```shell
-git submodule upgrade --remote --merge
+git submodule update --remote --merge
 ```
 
 Once the submodule has been upgraded, continue to the [next section](#step-3-theme-configuration).
@@ -107,6 +109,10 @@ Using your preferred language, simply create this new file in `config/_default/`
 
 Once the values have been moved to the new location, these parameters should be deleted from their original locations.
 
+### Menus.toml
+
+As the theme is now aware of languages, the `menus.toml` file should also be renamed to include a language code. Rename the existing `menus.toml` to `menus.[lang-code].toml`, where the language code matches the code used in the `languages.toml` file in the previous section.
+
 ### Config.toml
 
 The `config.toml` file now only contains base Hugo configuration values. Other than removing the language-specific strings above, there are only two changes to consider.
@@ -168,12 +174,14 @@ For the full list of supported parameters, refer to the [Configuration]({{< ref
 
 ## Step 4: Move assets
 
-All site assets now use Hugo Pipes to build an optimised version of your project. In order for the theme to locate your files, any previously static assets used in the theme need to be moved to the Hugo assets folder.
+All site assets, with the exception of favicons, now use Hugo Pipes to build an optimised version of your project. In order for the theme to locate your files, any previously static theme assets need to be moved to the Hugo assets folder. Primarily this is the author image and site logo:
 
 `static/me.jpg` **&rarr;** `assets/me.jpg`  
 `static/logo.jpg` **&rarr;** `assets/logo.jpg`
 
-If you have provided an author image or site logo, simply move these assets from the `static/` folder to the `assets/` folder. If you use the same directory structure the theme will know where to find these files automatically. If you would like to provide a new path, update the `logo` and `author.image` config values accordingly.
+If you have provided an author image or site logo, simply move these assets from `static/` to `assets/`. If you use the same directory structure the theme will know where to find these files automatically. If you would like to provide a new path, update the `logo` and `author.image` config values accordingly.
+
+Note that this step does not apply to any assets in your project that are actually static. For example, a PDF file that you link directly to from within an article is a static asset. These files should remain in the `static/` directory to ensure they are copied to the output folder when Hugo builds the site.
 
 ## Step 5: Check content