From 12edd7363c7a58942b97969f4c4d032941a9dc7b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B8rn=20Erik=20Pedersen?=
 <bjorn.erik.pedersen@gmail.com>
Date: Tue, 20 Dec 2022 15:10:55 +0100
Subject: [PATCH] Add some docs for workspaces

---
 README.md                              |  9 ++++++++
 content/en/hugo-modules/use-modules.md | 30 ++++++++++++++++++++++++++
 hugo.work                              |  4 ++++
 3 files changed, 43 insertions(+)
 create mode 100644 hugo.work

diff --git a/README.md b/README.md
index 072714a02..730ad5fc8 100644
--- a/README.md
+++ b/README.md
@@ -19,6 +19,15 @@ Spelling fixes are most welcomed, and if you want to contribute longer sections
 * For example, try to find short snippets that teaches people about the concept. If the example is also useful as-is (copy and paste), then great. Don't list long and similar examples just so people can use them on their sites.
 * Hugo has users from all over the world, so easy to understand and [simple English](https://simple.wikipedia.org/wiki/Basic_English) is good.
 
+
+## Edit the theme
+
+If you want to do docs-related theme changes, the simplest way is to have both `hugoDocs` and `gohugoioTheme` cloned as sibling directories, and then run:
+
+```
+HUGO_MODULE_WORKSPACE=hugo.work hugo server --ignoreVendorPaths "**"
+```
+
 ## Branches
 
 * The `master` branch is where the site is automatically built from, and is the place to put changes relevant to the current Hugo version.
diff --git a/content/en/hugo-modules/use-modules.md b/content/en/hugo-modules/use-modules.md
index 8870307b3..977a52bd6 100644
--- a/content/en/hugo-modules/use-modules.md
+++ b/content/en/hugo-modules/use-modules.md
@@ -135,3 +135,33 @@ Run `hugo mod clean` to delete the entire modules cache.
 Note that you can also configure the `modules` cache with a `maxAge`, see [File Caches](/getting-started/configuration/#configure-file-caches).
 
 Also see the [CLI Doc](/commands/hugo_mod_clean/).
+
+## Module Workspaces
+
+{{< new-in "0.109.0" >}}
+
+Workspace support was added in [Go 1.18](https://go.dev/blog/get-familiar-with-workspaces) and Hugo got solid support for it in the `v0.109.0` version.
+
+A common use case for a workspace is to simplify local development of a site with its theme modules.
+
+A workspace can be configured in a `*.work` file and activated with the [module.workspace](/hugo-modules/configuration/) setting, which for this use is commonly controlled via the `HUGO_MODULE_WORKSPACE` OS environment variable.
+
+See the [hugo.work](https://github.com/gohugoio/hugo/blob/master/hugo.work) file in the Hugo Docs repo for an example:
+
+```
+go 1.19
+
+use .
+use ../gohugoioTheme
+```
+
+Using the `use` directive, list all the modules you want to work on, pointing to its relative location. As in the example above, it's recommended to always include the main project (the ".") in the list.
+
+With that you can start the Hugo server with that workspace enabled:
+
+```
+HUGO_MODULE_WORKSPACE=hugo.work hugo server --ignoreVendorPaths "**"
+```
+
+The `--ignoreVendorPaths` flag is added above to ignore any of the vendored dependencies inside `_vendor`. If you don't use vendoring, you don't need that flag. But now the server is set up watching the files and directories in the workspace and you can see your local edits reloaded.
+
diff --git a/hugo.work b/hugo.work
new file mode 100644
index 000000000..a3c91ef28
--- /dev/null
+++ b/hugo.work
@@ -0,0 +1,4 @@
+go 1.19
+
+use .
+use ../gohugoioTheme