Single Hugo-module support: update CHANGELOG and docs (google#1743)

CHANGELOG.md

@@ -24,6 +24,10 @@ For the full list of changes, see the [release][0.8.0] notes.
 
 **Breaking changes**:
 
+- Docsy is packaged as a **single Hugo module** ([#1120]).
+  - For details, see [Use Docsy as a Hugo Module].
+- **Important**: non-Hugo-module projects should read the [Docsy NPM install
+  side-effect] note.
 - **Page feedback**, or [User feedback]:
   - In support of projects configuring analytics outside of Docsy, feedback
     functionality is enabled regardless of whether
@@ -41,10 +45,15 @@ For the full list of changes, see the [release][0.8.0] notes.
 
 **Other changes**:
 
+[#1120]: https://github.com/google/docsy/issues/1120
 [#1385]: https://github.com/google/docsy/issues/1385
 [#1726]: https://github.com/google/docsy/pull/1726
 [#1727]: https://github.com/google/docsy/pull/1727
 [0.8.0]: https://github.com/google/docsy/releases/v0.8.0/#FIXME
+[Docsy NPM install side-effect]:
+  https://docsy.dev/docs/get-started/other-options/#docsy-npm-install-side-effect
+[Use Docsy as a Hugo Module]:
+  https://www.docsy.dev/docs/get-started/docsy-as-module/
 [User feedback]:
   https://www.docsy.dev/docs/adding-content/feedback/#user-feedback
 

userguide/content/en/docs/get-started/docsy-as-module/installation-prerequisites.md

@@ -10,7 +10,7 @@ This page describes the prerequisites for building a site that uses Docsy as a H
 
 ## 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.
+You need a [recent **extended** version](https://github.com/gohugoio/hugo/releases) (version 0.110.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.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:
+If the result is `v0.109.0` 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
@@ -70,7 +70,7 @@ Hugo's commands for module management require that the Go programming language i
 
 ```console
 $ go version
-go version go1.20.5
+go version go1.21.4
 ```
 
 Ensure that you are using version 1.12 or higher.
@@ -84,7 +84,7 @@ Hugo's commands for module management require that the `git` client is installed
 
 ```console
 $ git version
-git version 2.41.0
+git version 2.42.1
 ```
 
 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.
@@ -138,11 +138,11 @@ You can check your current Node.js version by running `node -v`.  If you need to
 
    ```bash
    # Using Ubuntu
-   curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
+   curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
    sudo apt-get install -y nodejs
 
    # Using Debian, as root
-   curl -fsSL https://deb.nodesource.com/setup_18.x | bash -
+   curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
    apt-get install -y nodejs
    ```
 
@@ -152,10 +152,10 @@ You can check your current Node.js version by running `node -v`.  If you need to
 
    ```bash
    # As root
-   curl -fsSL https://rpm.nodesource.com/setup_18.x | bash -
+   curl -fsSL https://rpm.nodesource.com/setup_20.x | bash -
 
    # No root privileges
-   curl -fsSL https://rpm.nodesource.com/setup_18.x | sudo bash -
+   curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
    ```
 
 

userguide/content/en/docs/get-started/docsy-as-module/start-from-scratch.md

@@ -27,8 +27,6 @@ cat >> hugo.toml <<EOL
 proxy = "direct"
 [[module.imports]]
 path = "github.com/google/docsy"
-[[module.imports]]
-path = "github.com/google/docsy/dependencies"
 EOL
 hugo server
 {{< /tab >}}
@@ -43,11 +41,7 @@ proxy = "direct"^
 
 [[module.imports]]^
 
-path = "github.com/google/docsy"^
-
-[[module.imports]]^
-
-path = "github.com/google/docsy/dependencies")>>hugo.toml
+path = "github.com/google/docsy"
 hugo server
 {{< /tab >}}
 {{< /tabpane >}}
@@ -110,9 +104,6 @@ Add the settings in the following snippet at the end of your site's [configurati
   [[module.imports]]
     path = "github.com/google/docsy"
     disable = false
-  [[module.imports]]
-    path = "github.com/google/docsy/dependencies"
-    disable = false
 {{< /tab >}}
 {{< tab header="hugo.yaml" lang="yaml" >}}
 module:
@@ -123,8 +114,6 @@ module:
   imports:
     - path: github.com/google/docsy
       disable: false
-    - path: github.com/google/docsy/dependencies
-      disable: false
 {{< /tab >}}
 {{< tab header="hugo.json"  lang="json" >}}
 {
@@ -138,10 +127,6 @@ module:
       {
         "path": "github.com/google/docsy",
         "disable": false
-      },
-      {
-        "path": "github.com/google/docsy/dependencies",
-        "disable": false
       }
     ]
   }

userguide/content/en/docs/get-started/other-options.md

@@ -131,7 +131,7 @@ release][latest-lts].
 From your project root, run this command:
 
 ```
-npm install --save-dev autoprefixer postcss-cli postcss
+npm install --save-dev autoprefixer postcss-cli
 ```
 
 ## Option 1: Docsy as a Git submodule
@@ -190,6 +190,8 @@ If you are using hugo 0.110 or above, consider renaming your `config.toml` to `h
     (cd themes/docsy && npm install)
     ```
 
+    > **Important**: read the [Docsy NPM install side-effect] note.
+
 4.  (Optional but recommended) To avoid having to repeat the previous step every
     time you update Docsy, consider adding [NPM scripts][] like the following to
     your project's `package.json` file:
@@ -234,6 +236,8 @@ cd docsy
 npm install
 ```
 
+> **Important**: read the [Docsy NPM install side-effect] note.
+
 To work from the development version of Docsy (not recommended unless, for
 example, you plan to upstream changes to Docsy), omit the `-b v{{% param version
 %}}` argument from the clone command above.
@@ -259,9 +263,11 @@ You can use Docsy as an NPM module as follows:
 2.  Install Docsy, and postCSS (as [instructed earlier](#install-postcss)):
 
     ```console
-    npm install --save-dev google/docsy#semver:{{% param version %}} autoprefixer postcss-cli postcss
+    npm install --save-dev google/docsy#semver:{{% param version %}} autoprefixer postcss-cli
     ```
 
+    > **Important**: read the [Docsy NPM install side-effect] note.
+
 3.  Build or serve your new site using the usual Hugo commands, specifying the
     path to the Docsy theme files. For example, build your site as follows:
 
@@ -290,6 +296,29 @@ ln -s ../node_modules/docsy
 popd
 ```
 
+## Docsy NPM install side-effect
+
+{{% alert title="Important" color=warning %}}
+
+As of Docsy version [0.8.0], running `npm install` inside the Docsy theme
+directory will create a sibling folder named `github.com`, for example:
+
+```console
+$ ls themes
+docsy                   github.com
+```
+
+This is a workaround necessary to support Docsy's use as a single [Hugo module]
+([#1120]).
+
+[#1120]: https://github.com/google/docsy/issues/1120
+[0.8.0]: https://github.com/google/docsy/blob/main/CHANGELOG.md/#080
+[hugo module]: /docs/get-started/docsy-as-module/
+
+{{% /alert %}}
+
+[Docsy NPM install side-effect]: #docsy-npm-install-side-effect
+
 ## Preview your site
 
 To preview your site locally:

userguide/content/en/docs/updating/convert-site-to-module.md

@@ -23,8 +23,6 @@ cat >> hugo.toml <<EOL
 proxy = "direct"
 [[module.imports]]
 path = "github.com/google/docsy"
-[[module.imports]]
-path = "github.com/google/docsy/dependencies"
 EOL
 hugo server
 {{< /tab >}}
@@ -39,11 +37,7 @@ proxy = "direct"^
 
 [[module.imports]]^
 
-path = "github.com/google/docsy"^
-
-[[module.imports]]^
-
-path = "github.com/google/docsy/dependencies")>>hugo.toml
+path = "github.com/google/docsy")>>hugo.toml
 hugo server
 {{< /tab >}}
 {{< /tabpane >}}
@@ -97,17 +91,15 @@ Change this line to:
 {{< tabpane >}}
 {{< tab header="Configuration file:" disabled=true />}}
 {{< tab header="hugo.toml" lang="toml" >}}
-theme = ["github.com/google/docsy", "github.com/google/docsy/dependencies"]
+theme = ["github.com/google/docsy"]
 {{< /tab >}}
 {{< tab header="config.yaml" lang="yaml" >}}
 theme:
   - github.com/google/docsy
-  - github.com/google/docsy/dependencies
 {{< /tab >}}
 {{< tab header="hugo.json" lang="json" >}}
 "theme": [
-  "github.com/google/docsy",
-  "github.com/google/docsy/dependencies"
+  "github.com/google/docsy"
 ]
 {{< /tab >}}
 {{< /tabpane >}}
@@ -127,9 +119,6 @@ Alternatively, you can omit this line altogether and replace it with the setting
   [[module.imports]]
     path = "github.com/google/docsy"
     disable = false
-  [[module.imports]]
-    path = "github.com/google/docsy/dependencies"
-    disable = false
 {{< /tab >}}
 {{< tab header="hugo.yaml" lang="yaml" >}}
 module:
@@ -186,9 +175,8 @@ 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@v{{% param "version" %}}
-github.com/me/my-existing-site github.com/google/docsy/dependencies@v{{% param "version" %}}
-github.com/google/docsy/dependencies@v{{% param "version" %}} github.com/twbs/[email protected]+incompatible
-github.com/google/docsy/dependencies@v{{% param "version" %}} github.com/FortAwesome/[email protected]
+github.com/google/docsy@v{{% param "version" %}} github.com/twbs/[email protected]+incompatible
+github.com/google/docsy@v{{% param "version" %}} github.com/FortAwesome/[email protected]
 ```
 
 Make sure that three lines with dependencies `docsy`, `bootstrap` and `Font-Awesome` are listed. If not, please double check your config settings.
@@ -201,7 +189,6 @@ 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/dependencies"
 hugo: cleaned module cache for "github.com/twbs/bootstrap"
 ```
 {{% /alert %}}