introduction.md - hugo - [fork] hugo port for 9front
(HTM) git clone https://git.drkhsh.at/hugo.git
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) Submodules
(DIR) README
(DIR) LICENSE
---
introduction.md (9931B)
---
1 ---
2 title: Introduction
3 description: Configure your site using files, directories, and environment variables.
4 categories: []
5 keywords: []
6 weight: 10
7 ---
8
9 ## Sensible defaults
10
11 Hugo offers many configuration options, but its defaults are often sufficient. A new site requires only these settings:
12
13 {{< code-toggle file=hugo >}}
14 baseURL = 'https://example.org/'
15 languageCode = 'en-us'
16 title = 'My New Hugo Site'
17 {{< /code-toggle >}}
18
19 Only define settings that deviate from the defaults. A smaller configuration file is easier to read, understand, and debug. Keep your configuration concise.
20
21 > [!note]
22 > The best configuration file is a short configuration file.
23
24 ## Configuration file
25
26 Create a site configuration file in the root of your project directory, naming it `hugo.toml`, `hugo.yaml`, or `hugo.json`, with that order of precedence.
27
28 ```text
29 my-project/
30 └── hugo.toml
31 ```
32
33 > [!note]
34 > For versions v0.109.0 and earlier, the site configuration file was named `config`. While you can still use this name, it's recommended to switch to the newer naming convention, `hugo`.
35
36 A simple example:
37
38 {{< code-toggle file=hugo >}}
39 baseURL = 'https://example.org/'
40 languageCode = 'en-us'
41 title = 'ABC Widgets, Inc.'
42 [params]
43 subtitle = 'The Best Widgets on Earth'
44 [params.contact]
45 email = 'info@example.org'
46 phone = '+1 202-555-1212'
47 {{< /code-toggle >}}
48
49 To use a different configuration file when building your site, use the `--config` flag:
50
51 ```sh
52 hugo --config other.toml
53 ```
54
55 Combine two or more configuration files, with left-to-right precedence:
56
57 ```sh
58 hugo --config a.toml,b.yaml,c.json
59 ```
60
61 > [!note]
62 > See the specifications for each file format: [TOML], [YAML], and [JSON].
63
64 ## Configuration directory
65
66 Instead of a single site configuration file, split your configuration by [environment](g), root configuration key, and language. For example:
67
68 ```text
69 my-project/
70 └── config/
71 ├── _default/
72 │ ├── hugo.toml
73 │ ├── menus.en.toml
74 │ ├── menus.de.toml
75 │ └── params.toml
76 └── production/
77 └── params.toml
78 ```
79
80 The root configuration keys are {{< root-configuration-keys >}}.
81
82 > [!note]
83 > You must define `cascade` tables in the root configuration file. You cannot define `cascade` tables in a dedicated file. See issue [#12899] for details.
84
85 [#12899]: https://github.com/gohugoio/hugo/issues/12899
86
87 ### Omit the root key
88
89 When splitting the configuration by root key, omit the root key in the component file. For example, these are equivalent:
90
91 {{< code-toggle file=config/_default/hugo >}}
92 [params]
93 foo = 'bar'
94 {{< /code-toggle >}}
95
96 {{< code-toggle file=config/_default/params >}}
97 foo = 'bar'
98 {{< /code-toggle >}}
99
100 ### Recursive parsing
101
102 Hugo parses the `config` directory recursively, allowing you to organize the files into subdirectories. For example:
103
104 ```text
105 my-project/
106 └── config/
107 └── _default/
108 ├── navigation/
109 │ ├── menus.de.toml
110 │ └── menus.en.toml
111 └── hugo.toml
112 ```
113
114 ### Example
115
116 ```text
117 my-project/
118 └── config/
119 ├── _default/
120 │ ├── hugo.toml
121 │ ├── menus.en.toml
122 │ ├── menus.de.toml
123 │ └── params.toml
124 ├── production/
125 │ ├── hugo.toml
126 │ └── params.toml
127 └── staging/
128 ├── hugo.toml
129 └── params.toml
130 ```
131
132 Considering the structure above, when running `hugo --environment staging`, Hugo will use every setting from `config/_default` and merge `staging`'s on top of those.
133
134 Let's take an example to understand this better. Let's say you are using Google Analytics for your website. This requires you to specify a [Google tag ID] in your site configuration:
135
136 {{< code-toggle file=hugo >}}
137 [services.googleAnalytics]
138 ID = 'G-XXXXXXXXX'
139 {{< /code-toggle >}}
140
141 Now consider the following scenario:
142
143 1. You don't want to load the analytics code when running `hugo server`.
144 1. You want to use different Google tag IDs for your production and staging environments. For example:
145 - `G-PPPPPPPPP` for production
146 - `G-SSSSSSSSS` for staging
147
148 To satisfy these requirements, configure your site as follows:
149
150 1. `config/_default/hugo.toml`
151 - Exclude the `services.googleAnalytics` section. This will prevent loading of the analytics code when you run `hugo server`.
152 - By default, Hugo sets its `environment` to `development` when running `hugo server`. In the absence of a `config/development` directory, Hugo uses the `config/_default` directory.
153 1. `config/production/hugo.toml`
154 - Include this section only:
155
156 {{< code-toggle file=hugo >}}
157 [services.googleAnalytics]
158 ID = 'G-PPPPPPPPP'
159 {{< /code-toggle >}}
160
161 - You do not need to include other parameters in this file. Include only those parameters that are specific to your production environment. Hugo will merge these parameters with the default configuration.
162 - By default, Hugo sets its `environment` to `production` when running `hugo`. The analytics code will use the `G-PPPPPPPPP` tag ID.
163
164 1. `config/staging/hugo.toml`
165
166 - Include this section only:
167
168 {{< code-toggle file=hugo >}}
169 [services.googleAnalytics]
170 ID = 'G-SSSSSSSSS'
171 {{< /code-toggle >}}
172
173 - You do not need to include other parameters in this file. Include only those parameters that are specific to your staging environment. Hugo will merge these parameters with the default configuration.
174 - To build your staging site, run `hugo --environment staging`. The analytics code will use the `G-SSSSSSSSS` tag ID.
175
176 ## Merge configuration settings
177
178 Hugo merges configuration settings from themes and modules, prioritizing the project's own settings. Given this simplified project structure with two themes:
179
180 ```text
181 project/
182 ├── themes/
183 │ ├── theme-a/
184 │ │ └── hugo.toml
185 │ └── theme-b/
186 │ └── hugo.toml
187 └── hugo.toml
188 ```
189
190 and this project-level configuration:
191
192 {{< code-toggle file=hugo >}}
193 baseURL = 'https://example.org/'
194 languageCode = 'en-us'
195 title = 'My New Hugo Site'
196 theme = ['theme-a','theme-b']
197 {{< /code-toggle >}}
198
199 Hugo merges settings in this order:
200
201 1. Project configuration (`hugo.toml` in the project root)
202 1. `theme-a` configuration
203 1. `theme-b` configuration
204
205 The `_merge` setting within each top-level configuration key controls _which_ settings are merged and _how_ they are merged.
206
207 The value for `_merge` can be one of:
208
209 none
210 : No merge.
211
212 shallow
213 : Only add values for new keys.
214
215 deep
216 : Add values for new keys, merge existing.
217
218 Note that you don't need to be so verbose as in the default setup below; a `_merge` value higher up will be inherited if not set.
219
220 {{< code-toggle file=hugo dataKey="config_helpers.mergeStrategy" skipHeader=true />}}
221
222 ## Environment variables
223
224 You can also configure settings using operating system environment variables:
225
226 ```sh
227 export HUGO_BASEURL=https://example.org/
228 export HUGO_ENABLEGITINFO=true
229 export HUGO_ENVIRONMENT=staging
230 hugo
231 ```
232
233 The above sets the [`baseURL`], [`enableGitInfo`], and [`environment`] configuration options and then builds your site.
234
235 > [!note]
236 > An environment variable takes precedence over the values set in the configuration file. This means that if you set a configuration value with both an environment variable and in the configuration file, the value in the environment variable will be used.
237
238 Environment variables simplify configuration for [CI/CD](g) deployments like GitHub Pages, GitLab Pages, and Netlify by allowing you to set values directly within their respective configuration and workflow files.
239
240 > [!note]
241 > Environment variable names must be prefixed with `HUGO_`.
242 >
243 > To set custom site parameters, prefix the name with `HUGO_PARAMS_`.
244
245 For snake_case variable names, the standard `HUGO_` prefix won't work. Hugo infers the delimiter from the first character following `HUGO`. This allows for variations like `HUGOxPARAMSxAPI_KEY=abcdefgh` using any [permitted delimiter].
246
247 In addition to configuring standard settings, environment variables may be used to override default values for certain internal settings:
248
249 DART_SASS_BINARY
250 : (`string`) The absolute path to the Dart Sass executable. By default, Hugo searches for the executable in each of the paths in the `PATH` environment variable.
251
252 HUGO_FILE_LOG_FORMAT
253 : (`string`) A format string for the file path, line number, and column number displayed when reporting errors, or when calling the `Position` method from a shortcode or Markdown render hook. Valid tokens are `:file`, `:line`, and `:col`. Default is `:file::line::col`.
254
255 HUGO_MEMORYLIMIT
256 : {{< new-in 0.123.0 />}}
257 : (`int`) The maximum amount of system memory, in gigabytes, that Hugo can use while rendering your site. Default is 25% of total system memory. Note that `HUGO_MEMORYLIMIT` is a "best effort" setting. Don't expect Hugo to build a million pages with only 1 GB of memory. You can get more information about how this behaves during the build by building with `hugo --logLevel info` and look for the `dynacache` label.
258
259 HUGO_NUMWORKERMULTIPLIER
260 : (`int`) The number of workers used in parallel processing. Default is the number of logical CPUs.
261
262 ## Current configuration
263
264 Display the complete site configuration with:
265
266 ```sh
267 hugo config
268 ```
269
270 Display a specific configuration setting with:
271
272 ```sh
273 hugo config | grep [key]
274 ```
275
276 Display the configured file mounts with:
277
278 ```sh
279 hugo config mounts
280 ```
281
282 [`baseURL`]: /configuration/all#baseurl
283 [`enableGitInfo`]: /configuration/all#enablegitinfo
284 [`environment`]: /configuration/all#environment
285 [Google tag ID]: https://support.google.com/tagmanager/answer/12326985?hl=en
286 [JSON]: https://datatracker.ietf.org/doc/html/rfc7159
287 [permitted delimiter]: https://pubs.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap08.html
288 [TOML]: https://toml.io/en/latest
289 [YAML]: https://yaml.org/spec/