Hacking docsy theme (using hugo workspace)

Support of local builds, using docsy theme in a sibling folder

README.md

@@ -101,6 +101,40 @@ docker-compose rm
 For more information see the [Docker Compose
 documentation](https://docs.docker.com/compose/gettingstarted/).
 
+## Hacking the docsy theme
+
+Make sure your installed go version is `1.18` or higher and you are running hugo version `v0.109.0` or higher.
+
+Clone the latest version of the docsy theme into the parent folder of your project. The newly created repo should now reside in a sibling folder of our site's root folder.
+
+```shell
+cd root-of-your-site
+git clone --branch v0.7.1 https://github.com/google/docsy.git ../docsy
+```
+
+Now run:
+
+```shell
+HUGO_MODULE_WORKSPACE=hugo.work hugo server --ignoreVendorPaths "**"
+```
+
+or, when using npm, prepend `local` to the script you want to invoke, e.g.:
+
+```shell
+npm run local serve
+```
+
+By using the `HUGO_MODULE_WORKSPACE` directive (either directly or via prefix `local` when using npm), the server now watches all files and directories inside the sibling directory `../docsy` , too. Any changes inside the local `docsy` theme clone are  now immediately picked up (hot reload), you can instantly see the effect of your local edits.
+
+In the command above, we used the environment variable `HUGO_MODULE_WORKSPACE` to tell hugo about the local workspace file `hugo.work`. Alternatively, you can declare the workspace file inside your settings file `hugo.toml`:
+
+```toml
+[module]
+  workspace = "hugo.work" 
+```
+
+Your project's `hugo.toml` file already contains these lines, the directive for workspace assignment is commented out, however. Remove the trailing '#' character so that this line takes effect.
+
 ## Troubleshooting
 
 As you run the website locally, you may run into the following error:

hugo.toml

@@ -220,8 +220,9 @@ enable = false
 # hugo module configuration
 
 [module]
-  # uncomment line below for temporary local development of module
-  # replacements = "github.com/google/docsy -> ../../docsy"
+  # uncomment line below for local development of module
+  # needs hugo v0.109.0 or higher and go 1.18 or higher
+  # workspace = "hugo.work" 
   [module.hugoVersion]
     extended = true
     min = "0.110.0"

hugo.work

@@ -0,0 +1,8 @@
+go 1.19
+
+use .
+
+// example site and docsy share the same parent folder
+use ../docsy/
+// or if you cloned docsy repo to directory 'themes'
+// use ./themes/docsy/

hugo.work.sum

@@ -0,0 +1,3 @@
+github.com/google/docsy/dependencies v0.6.0 h1:BFXDCINbp8ZuUGl/mrHjMfhCg+b1YX+hVLAA5fGW7Pc=
+github.com/google/docsy/dependencies v0.6.0/go.mod h1:EDGc2znMbGUw0RW5kWwy2oGgLt0iVXBmoq4UOqstuNE=
+github.com/google/docsy/dependencies v0.7.1 h1:NbzYKJYMin2q50xdWSUzR2c9gCp7zR/XHDBcxklEcTQ=

package.json

@@ -13,13 +13,15 @@
     "_check:links": "echo IMPLEMENTATION PENDING for check-links; echo",
     "_hugo": "hugo --cleanDestinationDir",
     "_hugo-dev": "npm run _hugo -- -e dev -DFE",
+    "_local": "cross-env HUGO_MODULE_WORKSPACE=hugo.work",
     "_serve": "npm run _hugo-dev -- --minify serve",
     "build:preview": "npm run _hugo-dev -- --minify --baseURL \"${DEPLOY_PRIME_URL:-/}\"",
     "build:production": "npm run _hugo -- --minify",
     "build": "npm run _build",
     "check:links:all": "HTMLTEST_ARGS= npm run _check:links",
     "check:links": "npm run _check:links",
     "clean": "rm -Rf public/* resources",
+    "local": "npm run _local -- npm run",
     "make:public": "git init -b main public",
     "precheck:links:all": "npm run build",
     "precheck:links": "npm run build",
@@ -32,6 +34,7 @@
   },
   "devDependencies": {
     "autoprefixer": "^10.4.14",
+    "cross-env": "^7.0.3",
     "hugo-extended": "0.113.0",
     "postcss-cli": "^10.1.0"
   }