content: Clarify modulule initializaton

Closes gohugoio#3398

Author: jmooring

content/en/hugo-modules/use-modules.md

@@ -1,154 +1,200 @@
 ---
 title: Use Hugo Modules
-description: How to use Hugo Modules.
+description: Use modules to manage the content, layout, presentation, and behavior of your site.
 categories: []
 keywords: []
 weight: 20
 aliases: [/themes/usage/,/themes/installing/,/installing-and-using-themes/]
 ---
 
-## Prerequisite
+> [!note]
+> To work with modules you must install [Git][] and [Go][] 1.18 or later.
 
-{{% include "/_common/gomodules-info.md" %}}
+## Introduction
 
-## Initialize a new module
+{{% glossary-term module %}}
 
-Use `hugo mod init` to initialize a new Hugo Module. If it fails to guess the module path, you must provide it as an argument, e.g.:
+- Modules can be imported in any combination or sequence.
+- Module imports are recursive; importing Module A can trigger the import of Module B, and so on.
+- Modules can provide configuration files and directories, subject to the constraints described in the [merge configuration settings][] section of the documentation.
+- External directories, including those from non-Hugo projects, can be mounted to create a [unified file system](g).
+
+## Import
+
+To import a module, first initialize the project itself as a module. For example:
 
 ```sh
-hugo mod init github.com/<your_user>/<your_project>
+hugo mod init github.com/user/project
 ```
 
-Also see the [CLI Doc](/commands/hugo_mod_init/).
+This will generate a [`go.mod`][] file in the project root.
+
+> [!note]
+> The module name is a unique identifier rather than a hosting requirement. Using a name like `github.com/user/project` is a common convention but it does not mean you must use Git or host your code on GitHub. You can use any name you like if you do not plan to have others import your project as a module. For example, you could use a simple name such as `my-project` when you run the initialization command.
 
-## Use a module for a theme
+Then define one or more imports in your site configuration. This contrived example imports three modules, each containing custom shortcodes:
 
-The easiest way to use a Module for a theme is to import it in the configuration.
+{{< code-toggle file=hugo >}}
+[module]
+  [[module.imports]]
+    path = 'shortcodes-a'
+  [[module.imports]]
+    path = '/home/user/shortcodes-b'
+  [[module.imports]]
+    path = 'github.com/user/shortcodes-c'
+{{< /code-toggle >}}
 
-1. Initialize the hugo module system: `hugo mod init github.com/<your_user>/<your_project>`
-1. Import the theme:
+Import precedence is top-down. For example, if `shortcodes-a`, `shortcodes-b`, and `shortcodes-c` each define an `image` shortcode, the `image` shortcode from `shortcodes-a` will take effect.
 
-    {{< code-toggle file=hugo >}}
-    [module]
-      [[module.imports]]
-        path = "github.com/spf13/hyde"
-    {{< /code-toggle >}}
+> [!note]
+> If multiple modules contain data files or [translation tables](g) with identical paths, the data is deeply merged, following top-down precedence.
 
-## Update modules
+When you build your site, Hugo will:
 
-Modules will be downloaded and added when you add them as imports to your configuration. See [configure modules](/configuration/module/#imports).
+1. Download the modules
+1. Cache them for future use
+1. Generate a [`go.sum`][] file in the project root
 
-To update or manage versions, you can use `hugo mod get`.
+See [configuring module imports][] for details and options.
 
-Some examples:
+## Update
 
-### Update all modules
+When you import a module, Hugo creates `go.mod` and `go.sum` files in your project root, storing version and checksum data. Clearing the module cache and rebuilding will re-download the originally imported module version, as specified in the `go.mod` file, ensuring consistent builds. Modules can be updated to other versions as needed.
+
+To update a module to the latest version:
 
 ```sh
-hugo mod get -u
+hugo mod get -u github.com/user/shortcodes-c
 ```
 
-### Update all modules recursively
+To update a module to a specific version:
 
 ```sh
-hugo mod get -u ./...
+hugo mod get -u github.com/user/shortcodes-c@v0.42.0
 ```
 
-### Update one module
+To update all modules to the latest version:
 
 ```sh
-hugo mod get -u github.com/gohugoio/myShortcodes
+hugo mod get -u
 ```
 
-### Get a specific version
+To recursively update all modules to the latest version:
 
 ```sh
-hugo mod get github.com/gohugoio/myShortcodes@v1.0.7
+hugo mod get -u ./...
 ```
 
-Also see the [CLI Doc](/commands/hugo_mod_get/).
-
-## Make and test changes in a module
+## Tidy
 
-One way to do local development of a module imported in a project is to add a replace directive to a local directory with the source in `go.mod`:
+To remove unused entries from the `go.mod` and `go.sum` files:
 
 ```sh
-replace github.com/bep/hugotestmods/mypartials => /Users/bep/hugotestmods/mypartials
+hugo mod tidy
 ```
 
-If you have the `hugo server` running, the configuration will be reloaded and `/Users/bep/hugotestmods/mypartials` put on the watch list.
+## Cache
 
-Instead of modifying the `go.mod` files, you can also use the modules configuration [`replacements`](/configuration/module/#top-level-options) option.
+Hugo caches modules to avoid repeated downloads during site builds. By default, these are stored in the `modules` directory within the [`cacheDir`][].
 
-## Print dependency graph
+To clean the module cache for the current project:
 
-Use `hugo mod graph` from the relevant module directory and it will print the dependency graph, including vendoring, module replacement or disabled status.
-
-E.g.:
+```sh
+hugo mod clean
+```
 
-```txt
-hugo mod graph
+To clean the module cache for all projects:
 
-github.com/bep/my-modular-site github.com/bep/hugotestmods/mymounts@v1.2.0
-github.com/bep/my-modular-site github.com/bep/hugotestmods/mypartials@v1.0.7
-github.com/bep/hugotestmods/mypartials@v1.0.7 github.com/bep/hugotestmods/myassets@v1.0.4
-github.com/bep/hugotestmods/mypartials@v1.0.7 github.com/bep/hugotestmods/myv2@v1.0.0
-DISABLED github.com/bep/my-modular-site github.com/spf13/hyde@v0.0.0-20190427180251-e36f5799b396
-github.com/bep/my-modular-site github.com/bep/hugo-fresh@v1.0.1
-github.com/bep/my-modular-site in-themesdir
+```sh
+hugo mod clean --all
 ```
 
-Also see the [CLI Doc](/commands/hugo_mod_graph/).
+For details on cache location and eviction, see [configuring file caches][].
 
-## Vendor your modules
+## Vendor
 
-`hugo mod vendor` will write all the module dependencies to a `_vendor` directory, which will then be used for all subsequent builds.
+{{% glossary-term vendor %}}
 
-Note that:
+Vendoring a module provides the benefits described above and allows for local inspection of its [components](g).
 
-- You can run `hugo mod vendor` on any level in the module tree.
-- Vendoring will not store modules stored in your `themes` directory.
-- Most commands accept a `--ignoreVendorPaths` flag, which will then not use the vendored modules in `_vendor` for the module paths matching the given [glob pattern](g).
-
-Also see the [CLI Doc](/commands/hugo_mod_vendor/).
+```sh
+hugo mod vendor
+```
 
-## Tidy go.mod, go.sum
+This command creates a `_vendor` directory containing copies of all imported modules, used in subsequent builds. Note that:
 
-Run `hugo mod tidy` to remove unused entries in `go.mod` and `go.sum`.
+- The `hugo mod vendor` command can be run from any module tree level.
+- Modules within the `themes` directory are not vendored.
+- The `--ignoreVendorPaths` flag allows you to exclude vendored modules matching a [glob pattern](g) from specific commands.
 
-Also see the [CLI Doc](/commands/hugo_mod_clean/).
+> [!important]
+> Instead of modifying files directly within the `_vendor` directory, override them by creating a corresponding file with the same relative path in your project's root.
 
-## Clean module cache
+To remove the vendored modules, delete the `_vendor` directory.
 
-Run `hugo mod clean` to delete the entire modules cache.
+## Replace
 
-Note that you can also configure the `modules` cache with a `maxAge`. See [configure caches](/configuration/caches/).
+For local module development, use a `replace` directive in `go.mod` pointing to your local directory:
 
-Also see the [CLI Doc](/commands/hugo_mod_clean/).
+```text
+replace github.com/user/module => /home/user/projects/module
+```
 
-## Module workspaces
+With `hugo serve`r running, this change will trigger a configuration reload and add the local directory to the watch list. Alternatively, configure replacements by setting the [`replacements`][] parameter in your site configuration.
 
-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.
+## Workspace
 
-A common use case for a workspace is to simplify local development of a site with its theme modules.
+{{% glossary-term "workspace" %}}
 
-A workspace can be configured in a `*.work` file and activated with the [module.workspace](/configuration/module/) setting, which for this use is commonly controlled via the `HUGO_MODULE_WORKSPACE` OS environment variable.
+Workspaces simplify local development of sites with modules. Create a `.work` file to define a workspace, and activate it via the [`workspace`][] configuration parameter or the `HUGO_MODULE_WORKSPACE` environment variable.
 
-See the [hugo.work](https://github.com/gohugoio/hugo/blob/master/docs/hugo.work) file in the Hugo Docs repo for an example:
+A `.work` file example:
 
 ```text
-go 1.20
+go 1.24
 
 use .
-use ../gohugoioTheme
+use ../my-hugo-module
 ```
 
-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:
+Use the `use` directive to list module paths, including the main project (`.`). Start the Hugo server with the workspace enabled:
 
 ```sh
 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.
+The `--ignoreVendorPaths` flag, used to ignore vendored dependencies (if applicable), enables live reloading of local edits within the workspace.
+
+## Graph
+
+To generate a [dependency graph](g), including vendoring, module replacement, and disabled module information, execute `hugo mod graph` within the target module directory. For example:
+
+```sh
+$ hugo mod graph
+
+github.com/bep/my-modular-site github.com/bep/hugotestmods/mymounts@v1.2.0
+github.com/bep/my-modular-site github.com/bep/hugotestmods/mypartials@v1.0.7
+github.com/bep/hugotestmods/mypartials@v1.0.7 github.com/bep/hugotestmods/myassets@v1.0.4
+github.com/bep/hugotestmods/mypartials@v1.0.7 github.com/bep/hugotestmods/myv2@v1.0.0
+DISABLED github.com/bep/my-modular-site github.com/spf13/hyde@v0.0.0-20190427180251-e36f5799b396
+github.com/bep/my-modular-site github.com/bep/hugo-fresh@v1.0.1
+github.com/bep/my-modular-site in-themesdir
+```
+
+## Mounts
+
+Imported modules automatically mount their component directories to Hugo's [unified file system](g). You can also manually mount any directory, including those from non-Hugo projects, to component directories.
+
+See [configuring module mounts][] for details.
+
+[`cacheDir`]: /configuration/all/#cachedir
+[`go.mod`]: https://go.dev/ref/mod#go-mod-file
+[`go.sum`]: https://go.dev/ref/mod#go-sum-files
+[`replacements`]: /configuration/module/#replacements
+[`workspace`]: /configuration/module/#workspace
+[configuring file caches]: /configuration/caches/
+[configuring module imports]: /configuration/module/#imports
+[configuring module mounts]: /configuration/module/#mounts
+[Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
+[Go]: https://go.dev/doc/install
+[merge configuration settings]: /configuration/introduction/#merge-configuration-settings

content/en/quick-reference/glossary/dependency-graph.md

@@ -0,0 +1,5 @@
+---
+title: dependency graph
+---
+
+A _dependency graph_ visually represents the relationships between the [_modules_](g) used in a Hugo project. It shows how modules depend on each other, forming a network of dependencies.

content/en/quick-reference/glossary/workspace.md

@@ -0,0 +1,7 @@
+---
+title: workspace
+params:
+  reference: /hugo-modules/use-modules/#workspace
+---
+
+A _workspace_ is a collection of [_modules_](g) on disk.