diff options
author | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2023-05-27 17:02:23 +0200 |
---|---|---|
committer | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2023-05-27 17:02:23 +0200 |
commit | a838a27e4c82626f9b3227e02a157119673e5dcf (patch) | |
tree | 9d220eadc3fcaedfd77be3fa466fec14e038cfd1 /docs/content/en/getting-started | |
parent | 273d9f69a6cb46ce632b340ebb1191e2e083323b (diff) | |
parent | d3927310d5b2404c3238f9b899db3329ea516490 (diff) | |
download | hugo-a838a27e4c82626f9b3227e02a157119673e5dcf.tar.gz hugo-a838a27e4c82626f9b3227e02a157119673e5dcf.zip |
Merge commit 'd3927310d5b2404c3238f9b899db3329ea516490'
Diffstat (limited to 'docs/content/en/getting-started')
-rw-r--r-- | docs/content/en/getting-started/configuration.md | 58 | ||||
-rw-r--r-- | docs/content/en/getting-started/directory-structure.md | 4 | ||||
-rw-r--r-- | docs/content/en/getting-started/quick-start.md | 8 |
3 files changed, 35 insertions, 35 deletions
diff --git a/docs/content/en/getting-started/configuration.md b/docs/content/en/getting-started/configuration.md index e47d3c942..53b444bb6 100644 --- a/docs/content/en/getting-started/configuration.md +++ b/docs/content/en/getting-started/configuration.md @@ -15,8 +15,8 @@ toc: true ## Configuration File -Hugo uses the `config.toml`, `config.yaml`, or `config.json` (if found in the -site root) as the default site config file. +Hugo uses the `hugo.toml`, `hugo.yaml`, or `hugo.json` (if found in the +site root) as the default site configuration file. The user can choose to override that default with one or more site config files using the command-line `--config` switch. @@ -45,7 +45,7 @@ In addition to using a single site config file, one can use the `configDir` dire - Each file represents a configuration root object, such as `params.toml` for `[Params]`, `menu(s).toml` for `[Menu]`, `languages.toml` for `[Languages]` etc... - Each file's content must be top-level, for example: -{{< code-toggle file="config" >}} +{{< code-toggle file="hugo" >}} [Params] foo = "bar" {{< /code-toggle >}} @@ -61,35 +61,35 @@ foo = "bar" ```txt ├── config │ ├── _default -│ │ ├── config.toml +│ │ ├── hugo.toml │ │ ├── languages.toml │ │ ├── menus.en.toml │ │ ├── menus.zh.toml │ │ └── params.toml │ ├── production -│ │ ├── config.toml +│ │ ├── hugo.toml │ │ └── params.toml │ └── staging -│ ├── config.toml +│ ├── hugo.toml │ └── params.toml ``` 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. -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 `googleAnalytics = "G-XXXXXXXX"` in `config.toml`. Now consider the following scenario: +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 `googleAnalytics = "G-XXXXXXXX"` in `hugo.toml`. Now consider the following scenario: - You don't want the Analytics code to be loaded in development i.e. in your `localhost` - You want to use separate googleAnalytics IDs for your production & staging environments (say): - `G-PPPPPPPP` for production - `G-SSSSSSSS` for staging -This is how you need to configure your `config.toml` files considering the above scenario: -1. In `_default/config.toml` you don't need to mention `googleAnalytics` parameter at all. This ensures that no Google Analytics code is loaded in your development server i.e. when you run `hugo server`. This works since, by default Hugo sets `Environment=development` when you run `hugo server` which uses the config files from `_default` folder -2. In `production/config.toml` you just need to have one line: +This is how you need to configure your `hugo.toml` files considering the above scenario: +1. In `_default/hugo.toml` you don't need to mention `googleAnalytics` parameter at all. This ensures that no Google Analytics code is loaded in your development server i.e. when you run `hugo server`. This works since, by default Hugo sets `Environment=development` when you run `hugo server` which uses the config files from `_default` folder +2. In `production/hugo.toml` you just need to have one line: ```googleAnalytics = "G-PPPPPPPP"``` - You don't need to mention all other parameters like `title`, `baseURL`, `theme` etc. again in this config file. You need to mention only those parameters which are different or new for the production environment. This is due to the fact that Hugo is going to __merge__ this on top of `_default/config.toml`. Now when you run `hugo` (build command), by default hugo sets `Environment=production`, so the `G-PPPPPPPP` analytics code will be there in your production website -3. Similarly in `staging/config.toml` you just need to have one line: + You don't need to mention all other parameters like `title`, `baseURL`, `theme` etc. again in this config file. You need to mention only those parameters which are different or new for the production environment. This is due to the fact that Hugo is going to __merge__ this on top of `_default/hugo.toml`. Now when you run `hugo` (build command), by default hugo sets `Environment=production`, so the `G-PPPPPPPP` analytics code will be there in your production website +3. Similarly in `staging/hugo.toml` you just need to have one line: ```googleAnalytics = "G-SSSSSSSS"``` @@ -378,7 +378,7 @@ The directory to where Hugo will write the final static site (the HTML files etc ### related -: See [Related Content](/content-management/related/#configure-related-content). +See [Related Content](/content-management/related/#configure-related-content). ### relativeURLs @@ -494,7 +494,7 @@ enableemoji: true The `build` configuration section contains global build-related configuration options. -{{< code-toggle file="config">}} +{{< code-toggle file="hugo" >}} [build] useResourceCacheWhen="fallback" writeStats = false @@ -518,7 +518,7 @@ noJSConfigInAssets This is only relevant when running `hugo server`, and it allows to set HTTP headers during development, which allows you to test out your Content Security Policy and similar. The configuration format matches [Netlify's](https://docs.netlify.com/routing/headers/#syntax-for-the-netlify-configuration-file) with slightly more powerful [Glob matching](https://github.com/gobwas/glob): -{{< code-toggle file="config">}} +{{< code-toggle file="hugo" >}} [server] [[server.headers]] for = "/**" @@ -592,18 +592,18 @@ HUGO_NUMWORKERMULTIPLIER Similar to the template [lookup order], Hugo has a default set of rules for searching for a configuration file in the root of your website's source directory as a default behavior: -1. `./config.toml` -2. `./config.yaml` -3. `./config.json` +1. `./hugo.toml` +2. `./hugo.yaml` +3. `./hugo.json` -In your `config` file, you can direct Hugo as to how you want your website rendered, control your website's menus, and arbitrarily define site-wide parameters specific to your project. +In your configuration file, you can direct Hugo as to how you want your website rendered, control your website's menus, and arbitrarily define site-wide parameters specific to your project. ## Example Configuration The following is a typical example of a configuration file. The values nested under `params:` will populate the [`.Site.Params`] variable for use in [templates]: -{{< code-toggle file="config">}} +{{< code-toggle file="hugo" >}} baseURL: "https://yoursite.example.com/" title: "My Hugo Site" permalinks: @@ -650,13 +650,13 @@ To exclude specific files from the `content`, `data`, and `i18n` directories whe To ignore files ending with `.foo` or `.boo`: -{{< code-toggle copy=false >}} +{{< code-toggle copy=false file="hugo" >}} ignoreFiles = ['\.foo$', '\.boo$'] {{< /code-toggle >}} To ignore a file using the absolute file path: -{{< code-toggle copy=false >}} +{{< code-toggle copy=false file="hugo" >}} ignoreFiles = ['^/home/user/project/content/test\.md$'] {{< /code-toggle >}} @@ -664,11 +664,11 @@ ignoreFiles = ['^/home/user/project/content/test\.md$'] ### Configure Dates -Dates are important in Hugo, and you can configure how Hugo assigns dates to your content pages. You do this by adding a `frontmatter` section to your `config.toml`. +Dates are important in Hugo, and you can configure how Hugo assigns dates to your content pages. You do this by adding a `frontmatter` section to your `hugo.toml`. The default configuration is: -{{< code-toggle file="config" >}} +{{< code-toggle file="hugo" >}} [frontmatter] date = ["date", "publishDate", "lastmod"] lastmod = [":git", "lastmod", "date", "publishDate"] @@ -678,7 +678,7 @@ expiryDate = ["expiryDate"] If you, as an example, have a non-standard date parameter in some of your content, you can override the setting for `date`: -{{< code-toggle file="config" >}} +{{< code-toggle file="hugo" >}} [frontmatter] date = ["myDate", ":default"] {{< /code-toggle >}} @@ -695,7 +695,7 @@ The special date handlers are: An example: -{{< code-toggle file="config" >}} +{{< code-toggle file="hugo" >}} [frontmatter] lastmod = ["lastmod", ":fileModTime", ":default"] {{< /code-toggle >}} @@ -709,7 +709,7 @@ The above will try first to extract the value for `.Lastmod` starting with the ` An example: -{{< code-toggle file="config" >}} +{{< code-toggle file="hugo" >}} [frontmatter] date = [":filename", ":default"] {{< /code-toggle >}} @@ -734,7 +734,7 @@ Default configuration: Since Hugo 0.52 you can configure more than just the `cacheDir`. This is the default configuration: -{{< code-toggle >}} +{{< code-toggle file="hugo" >}} [caches] [caches.getjson] dir = ":cacheDir/:project" @@ -756,7 +756,7 @@ dir = ":cacheDir/modules" maxAge = -1 {{< /code-toggle >}} -You can override any of these cache settings in your own `config.toml`. +You can override any of these cache settings in your own `hugo.toml`. ### The keywords explained diff --git a/docs/content/en/getting-started/directory-structure.md b/docs/content/en/getting-started/directory-structure.md index da0f9c761..7618570b0 100644 --- a/docs/content/en/getting-started/directory-structure.md +++ b/docs/content/en/getting-started/directory-structure.md @@ -29,7 +29,7 @@ example/ ├── public/ ├── static/ ├── themes/ -└── config.toml +└── hugo.toml ``` ## Directory Structure Explained @@ -46,7 +46,7 @@ By default, Hugo will create new content files with at least `date`, `title` (in [`config`](/getting-started/configuration/) : Hugo ships with a large number of [configuration directives]. The [config directory](/getting-started/configuration/#configuration-directory) is where those directives are stored as JSON, YAML, or TOML files. Every root setting object can stand as its own file and structured by environments. -Projects with minimal settings and no need for environment awareness can use a single `config.toml` file at its root. +Projects with minimal settings and no need for environment awareness can use a single `hugo.toml` file at its root. Many sites may need little to no configuration, but Hugo ships with a large number of [configuration directives] for more granular directions on how you want Hugo to build your website. Note: config directory is not created by default. diff --git a/docs/content/en/getting-started/quick-start.md b/docs/content/en/getting-started/quick-start.md index da35c314c..167dfc0e1 100644 --- a/docs/content/en/getting-started/quick-start.md +++ b/docs/content/en/getting-started/quick-start.md @@ -23,7 +23,7 @@ In this tutorial you will: Before you begin this tutorial you must: -1. [Install Hugo] (the extended edition) +1. [Install Hugo] (extended edition, v0.112.0 or later) 1. [Install Git] You must also be comfortable working from the command line. @@ -51,7 +51,7 @@ hugo new site quickstart cd quickstart git init git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke themes/ananke -echo "theme = 'ananke'" >> config.toml +echo "theme = 'ananke'" >> hugo.toml hugo server ``` @@ -86,7 +86,7 @@ git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke themes/an Append a line to the site configuration file, indicating the current theme. ```text -echo "theme = 'ananke'" >> config.toml +echo "theme = 'ananke'" >> hugo.toml ``` Start Hugo's development server to view the site. @@ -152,7 +152,7 @@ Hugo's rendering engine conforms to the CommonMark [specification] for markdown. ## Configure the site -With your editor, open the [site configuration] file (`config.toml`) in the root of your project. +With your editor, open the [site configuration] file (`hugo.toml`) in the root of your project. ```text baseURL = 'http://example.org/' |