use-modules.md - hugo - [fork] hugo port for 9front
HTML git clone https://git.drkhsh.at/hugo.git
DIR Log
DIR Files
DIR Refs
DIR Submodules
DIR README
DIR LICENSE
---
use-modules.md (5095B)
---
1 ---
2 title: Use Hugo Modules
3 description: How to use Hugo Modules.
4 categories: []
5 keywords: []
6 weight: 20
7 aliases: [/themes/usage/,/themes/installing/,/installing-and-using-themes/]
8 ---
9
10 ## Prerequisite
11
12 {{% include "/_common/gomodules-info.md" %}}
13
14 ## Initialize a new module
15
16 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.:
17
18 ```sh
19 hugo mod init github.com/<your_user>/<your_project>
20 ```
21
22 Also see the [CLI Doc](/commands/hugo_mod_init/).
23
24 ## Use a module for a theme
25
26 The easiest way to use a Module for a theme is to import it in the configuration.
27
28 1. Initialize the hugo module system: `hugo mod init github.com/<your_user>/<your_project>`
29 1. Import the theme:
30
31 {{< code-toggle file=hugo >}}
32 [module]
33 [[module.imports]]
34 path = "github.com/spf13/hyde"
35 {{< /code-toggle >}}
36
37 ## Update modules
38
39 Modules will be downloaded and added when you add them as imports to your configuration. See [configure modules](/configuration/module/#imports).
40
41 To update or manage versions, you can use `hugo mod get`.
42
43 Some examples:
44
45 ### Update all modules
46
47 ```sh
48 hugo mod get -u
49 ```
50
51 ### Update all modules recursively
52
53 ```sh
54 hugo mod get -u ./...
55 ```
56
57 ### Update one module
58
59 ```sh
60 hugo mod get -u github.com/gohugoio/myShortcodes
61 ```
62
63 ### Get a specific version
64
65 ```sh
66 hugo mod get github.com/gohugoio/myShortcodes@v1.0.7
67 ```
68
69 Also see the [CLI Doc](/commands/hugo_mod_get/).
70
71 ## Make and test changes in a module
72
73 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`:
74
75 ```sh
76 replace github.com/bep/hugotestmods/mypartials => /Users/bep/hugotestmods/mypartials
77 ```
78
79 If you have the `hugo server` running, the configuration will be reloaded and `/Users/bep/hugotestmods/mypartials` put on the watch list.
80
81 Instead of modifying the `go.mod` files, you can also use the modules configuration [`replacements`](/configuration/module/#top-level-options) option.
82
83 ## Print dependency graph
84
85 Use `hugo mod graph` from the relevant module directory and it will print the dependency graph, including vendoring, module replacement or disabled status.
86
87 E.g.:
88
89 ```txt
90 hugo mod graph
91
92 github.com/bep/my-modular-site github.com/bep/hugotestmods/mymounts@v1.2.0
93 github.com/bep/my-modular-site github.com/bep/hugotestmods/mypartials@v1.0.7
94 github.com/bep/hugotestmods/mypartials@v1.0.7 github.com/bep/hugotestmods/myassets@v1.0.4
95 github.com/bep/hugotestmods/mypartials@v1.0.7 github.com/bep/hugotestmods/myv2@v1.0.0
96 DISABLED github.com/bep/my-modular-site github.com/spf13/hyde@v0.0.0-20190427180251-e36f5799b396
97 github.com/bep/my-modular-site github.com/bep/hugo-fresh@v1.0.1
98 github.com/bep/my-modular-site in-themesdir
99 ```
100
101 Also see the [CLI Doc](/commands/hugo_mod_graph/).
102
103 ## Vendor your modules
104
105 `hugo mod vendor` will write all the module dependencies to a `_vendor` directory, which will then be used for all subsequent builds.
106
107 Note that:
108
109 - You can run `hugo mod vendor` on any level in the module tree.
110 - Vendoring will not store modules stored in your `themes` directory.
111 - Most commands accept a `--ignoreVendorPaths` flag, which will then not use the vendored modules in `_vendor` for the module paths matching the given [glob](g) pattern.
112
113 Also see the [CLI Doc](/commands/hugo_mod_vendor/).
114
115 ## Tidy go.mod, go.sum
116
117 Run `hugo mod tidy` to remove unused entries in `go.mod` and `go.sum`.
118
119 Also see the [CLI Doc](/commands/hugo_mod_clean/).
120
121 ## Clean module cache
122
123 Run `hugo mod clean` to delete the entire modules cache.
124
125 Note that you can also configure the `modules` cache with a `maxAge`. See [configure caches](/configuration/caches/).
126
127 Also see the [CLI Doc](/commands/hugo_mod_clean/).
128
129 ## Module workspaces
130
131 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.
132
133 A common use case for a workspace is to simplify local development of a site with its theme modules.
134
135 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.
136
137 See the [hugo.work](https://github.com/gohugoio/hugo/blob/master/docs/hugo.work) file in the Hugo Docs repo for an example:
138
139 ```text
140 go 1.20
141
142 use .
143 use ../gohugoioTheme
144 ```
145
146 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.
147
148 With that you can start the Hugo server with that workspace enabled:
149
150 ```sh
151 HUGO_MODULE_WORKSPACE=hugo.work hugo server --ignoreVendorPaths "**"
152 ```
153
154 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.