mirror of
https://github.com/gohugoio/hugo.git
synced 2025-04-28 22:50:35 +03:00
Merge commit '90ad804505'
This commit is contained in:
Bjørn Erik Pedersen
commit
af23cdca9c
45 changed files with 366 additions and 156 deletions
|
|
@ -4,7 +4,6 @@ linktitle: Configuration
|
|||
description: How to configure your Hugo site.
|
||||
date: 2013-07-01
|
||||
publishdate: 2017-01-02
|
||||
lastmod: 2017-03-05
|
||||
categories: [getting started,fundamentals]
|
||||
keywords: [configuration,toml,yaml,json]
|
||||
menu:
|
||||
|
|
@ -18,7 +17,6 @@ aliases: [/overview/source-directory/,/overview/configuration/]
|
|||
toc: true
|
||||
---
|
||||
|
||||
|
||||
## Configuration File
|
||||
|
||||
Hugo uses the `config.toml`, `config.yaml`, or `config.json` (if found in the
|
||||
|
|
@ -77,6 +75,27 @@ foo = "bar"
|
|||
```
|
||||
|
||||
Considering the structure above, when running `hugo --environment staging`, Hugo will use every settings 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:
|
||||
- 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 serve`. This works since, by default Hugo sets `Environment=development` when you run `hugo serve` which uses the config files from `_default` folder
|
||||
2. In `production/config.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:
|
||||
|
||||
```googleAnalytics = "G-SSSSSSSS"```
|
||||
|
||||
Now you need to tell Hugo that you are using the staging environment. So your build command should be `hugo --environment staging` which will load the `G-SSSSSSSS` analytics code in your staging website
|
||||
|
||||
|
||||
{{% note %}}
|
||||
Default environments are __development__ with `hugo server` and __production__ with `hugo`.
|
||||
{{%/ note %}}
|
||||
|
|
@ -149,7 +168,7 @@ See [Configure File Caches](#configure-file-caches)
|
|||
|
||||
{{< new-in "0.86.0" >}}
|
||||
|
||||
Pass down down default configuration values (front matter) to pages in the content tree. The options in site config is the same as in page front matter, see [Front Matter Cascade](/content-management/front-matter#front-matter-cascade).
|
||||
Pass down default configuration values (front matter) to pages in the content tree. The options in site config is the same as in page front matter, see [Front Matter Cascade](/content-management/front-matter#front-matter-cascade).
|
||||
|
||||
### canonifyURLs
|
||||
|
||||
|
|
@ -271,7 +290,10 @@ See [Image Processing Config](/content-management/image-processing/#imaging-conf
|
|||
|
||||
**Default value:** ""
|
||||
|
||||
A language tag as defined by [RFC 5646](https://datatracker.ietf.org/doc/html/rfc5646). The internal [RSS template](https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/rss.xml) populates its `<language>` element with this value. The value is not used elsewhere.
|
||||
A language tag as defined by [RFC 5646](https://datatracker.ietf.org/doc/html/rfc5646). This value is used to populate:
|
||||
|
||||
- The `<language>` element in the internal [RSS template](https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/rss.xml)
|
||||
- The `lang` attribute of the `<html>` element in the internal [alias template](https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/alias.html)
|
||||
|
||||
### languages
|
||||
|
||||
|
|
|
|||
|
|
@ -31,6 +31,7 @@ Running the `hugo new site` generator from the command line will create a direct
|
|||
├── content
|
||||
├── data
|
||||
├── layouts
|
||||
├── public
|
||||
├── static
|
||||
└── themes
|
||||
```
|
||||
|
|
@ -45,7 +46,7 @@ The following is a high-level overview of each of the directories with links to
|
|||
By default, Hugo will create new content files with at least `date`, `title` (inferred from the file name), and `draft = true`. This saves time and promotes consistency for sites using multiple content types. You can create your own [archetypes][] with custom preconfigured front matter fields as well.
|
||||
|
||||
[`assets`][]
|
||||
: Stores all the files which need be processed by [Hugo Pipes]({{< ref "/hugo-pipes" >}}). Only the files whose `.Permalink` or `.RelPermalink` are used will be published to the `public` directory. Note: assets directory is not created by default.
|
||||
: Stores all the files which need be processed by [Hugo Pipes](/hugo-pipes/). Only the files whose `.Permalink` or `.RelPermalink` are used will be published to the `public` directory. Note: assets directory is not created by default.
|
||||
|
||||
[`config`](/getting-started/configuration/)
|
||||
: Hugo ships with a large number of [configuration directives][].
|
||||
|
|
@ -71,11 +72,11 @@ used by Hugo when generating your website. You can write these files in YAML, JS
|
|||
From **Hugo 0.31** you can have multiple static directories.
|
||||
{{% /note %}}
|
||||
|
||||
resources
|
||||
[`resources`][]
|
||||
: Caches some files to speed up generation. Can be also used by template authors to distribute built SASS files, so you don't have to have the preprocessor installed. Note: resources directory is not created by default.
|
||||
|
||||
|
||||
[archetypes]: /content-management/archetypes/
|
||||
[`assets`]: /hugo-pipes/introduction#asset-directory/
|
||||
[configuration directives]: /getting-started/configuration/#all-configuration-settings
|
||||
[`content`]: /content-management/organization/
|
||||
[content section]: /content-management/sections/
|
||||
|
|
@ -84,6 +85,7 @@ resources
|
|||
[homepage]: /templates/homepage/
|
||||
[`layouts`]: /templates/
|
||||
[`static`]: /content-management/static-files/
|
||||
[`resources`]: /getting-started/configuration/#configure-file-caches
|
||||
[lists]: /templates/list/
|
||||
[pagevars]: /variables/page/
|
||||
[partials]: /templates/partials/
|
||||
|
|
@ -93,4 +95,3 @@ resources
|
|||
[taxonomies]: /content-management/taxonomies/
|
||||
[taxonomy templates]: /templates/taxonomy-templates/
|
||||
[types]: /content-management/types/
|
||||
[`assets`]: {{< ref "/hugo-pipes/introduction#asset-directory" >}}
|
||||
|
|
|
|||
|
|
@ -30,6 +30,12 @@ Hugo in Action is a step-by-step guide to using Hugo to create static websites.
|
|||
|
||||
[Build Websites with Hugo - Fast Web Development with Markdown (2020)](https://pragprog.com/titles/bhhugo/) by Brian P. Hogan.
|
||||
|
||||
## Beginner tutorials
|
||||
|
||||
### Hugo tutorial by CloudCannon
|
||||
|
||||
[Step-by-step written tutorial](https://cloudcannon.com/community/learn/hugo-101/) to teach you the basics of creating a Hugo site.
|
||||
|
||||
## Video tutorials
|
||||
|
||||
### Video Playlist by Mike Dane
|
||||
|
|
|
|||
|
|
@ -109,6 +109,7 @@ scoop install hugo-extended
|
|||
#### Prerequisite Tools
|
||||
|
||||
* [Git][installgit]
|
||||
* [GCC][] (For Windows users only)
|
||||
* [Go (at least Go 1.11)](https://golang.org/dl/)
|
||||
|
||||
#### Fetch from GitHub
|
||||
|
|
@ -126,7 +127,14 @@ go install --tags extended
|
|||
Remove `--tags extended` if you do not want/need Sass/SCSS support.
|
||||
|
||||
{{% note %}}
|
||||
If you are a Windows user, substitute the `$HOME` environment variable above with `%USERPROFILE%`.
|
||||
|
||||
##### For installation on Windows
|
||||
|
||||
* Substitute the `$HOME` environment variable above with `%USERPROFILE%`.
|
||||
* If you install `--tags extended` version, you may encounter this error `"gcc": executable file not found in %PATH%`
|
||||
* Please make sure you have installed `gcc` command and add it to `%PATH%`.
|
||||
* "MinGW" is recommended, it has been tested and built successfully
|
||||
|
||||
{{% /note %}}
|
||||
|
||||
## macOS
|
||||
|
|
@ -289,21 +297,21 @@ If `hugo` is not in your `PATH`:
|
|||
|
||||
If your default shell is zsh:
|
||||
|
||||
```
|
||||
nano ~/.zprofile
|
||||
```
|
||||
|
||||
If your default shell is bash:
|
||||
|
||||
```
|
||||
nano ~/.bash_profile
|
||||
```
|
||||
```
|
||||
nano ~/.zprofile
|
||||
```
|
||||
|
||||
If your default shell is bash:
|
||||
|
||||
```
|
||||
nano ~/.bash_profile
|
||||
```
|
||||
|
||||
3. Insert a line to add `$HOME/bin` to your existing `PATH`.
|
||||
|
||||
```
|
||||
export PATH=$PATH:$HOME/bin
|
||||
```
|
||||
```
|
||||
export PATH=$PATH:$HOME/bin
|
||||
```
|
||||
|
||||
4. Save the file by pressing Control-X, then Y.
|
||||
|
||||
|
|
@ -358,7 +366,7 @@ The following aims to be a complete guide to installing Hugo on your Windows PC.
|
|||
|
||||
{{< youtube G7umPCU-8xc >}}
|
||||
|
||||
### Assumptions
|
||||
### Assumptions for Windows
|
||||
|
||||
1. You will use `C:\Hugo\Sites` as the starting point for your new project.
|
||||
2. You will use `C:\Hugo\bin` to store executable files.
|
||||
|
|
@ -376,7 +384,12 @@ You'll need a place to store the Hugo executable, your [content][], and the gene
|
|||
|
||||
1. Download the latest zipped Hugo executable from [Hugo Releases][releases].
|
||||
2. Extract all contents to your `..\Hugo\bin` folder.
|
||||
3. In PowerShell or your preferred CLI, add the `hugo.exe` executable to your PATH by navigating to `C:\Hugo\bin` (or the location of your hugo.exe file) and use the command `set PATH=%PATH%;C:\Hugo\bin`. If the `hugo` command does not work after a reboot, you may have to run the command prompt as administrator.
|
||||
3. Open Windows Command Line (cmd, "DOS") to add the `hugo.exe` executable to your PATH
|
||||
* do `set PATH=%PATH%;C:\Hugo\bin` to have hugo in PATH for the currently opened cmd box
|
||||
* do `setx PATH "%PATH%;C:\Hugo\bin"` to have hugo in PATH for every newly opened cmd box
|
||||
* note: "setx", not "set", plus syntax 'key "val"', not 'key=val'
|
||||
|
||||
> You may also use "Git CMD" from the [Git for Windows package](https://gitforwindows.org/) for the native Windows commands [set](https://ss64.com/nt/set.html) and [setx](https://ss64.com/nt/setx.html), but not "Git Bash", PowerShell, or any other "CLI" with different commands
|
||||
|
||||
### Less-technical Users
|
||||
|
||||
|
|
@ -468,11 +481,15 @@ Directory of C:\hugo\sites\example.com
|
|||
|
||||
In any of the [Linux distributions that support snaps][snaps], you may install the "extended" Sass/SCSS version with this command:
|
||||
|
||||
snap install hugo --channel=extended
|
||||
```
|
||||
snap install hugo --channel=extended
|
||||
```
|
||||
|
||||
To install the non-extended version without Sass/SCSS support:
|
||||
|
||||
snap install hugo
|
||||
```
|
||||
snap install hugo
|
||||
```
|
||||
|
||||
To switch between the two, use either `snap refresh hugo --channel=extended` or `snap refresh hugo --channel=stable`.
|
||||
|
||||
|
|
@ -484,7 +501,9 @@ Hugo installed via Snap can write only inside the user’s `$HOME` directory---a
|
|||
|
||||
[@anthonyfok](https://github.com/anthonyfok) and friends in the [Debian Go Packaging Team](https://go-team.pages.debian.net/) maintains an official hugo [Debian package](https://packages.debian.org/hugo) which is shared with [Ubuntu](https://packages.ubuntu.com/hugo) and is installable via `apt-get`:
|
||||
|
||||
sudo apt-get install hugo
|
||||
```
|
||||
sudo apt-get install hugo
|
||||
```
|
||||
|
||||
What this installs depends on your Debian/Ubuntu version. On Ubuntu bionic (18.04), this installs the non-extended version without Sass/SCSS support. On Ubuntu disco (19.04), this installs the extended version with Sass/SCSS support.
|
||||
|
||||
|
|
@ -495,14 +514,16 @@ This option is not recommended because the Hugo in Linux package managers for De
|
|||
You can also install Hugo from the Arch Linux [community](https://www.archlinux.org/packages/community/x86_64/hugo/) repository. Applies also to derivatives such as Manjaro.
|
||||
|
||||
```
|
||||
sudo pacman -Syu hugo
|
||||
sudo pacman -S hugo
|
||||
```
|
||||
|
||||
### Fedora, Red Hat and CentOS
|
||||
|
||||
Fedora maintains an [official package for Hugo](https://packages.fedoraproject.org/pkgs/hugo/hugo) which may be installed with:
|
||||
|
||||
sudo dnf install hugo
|
||||
```
|
||||
sudo dnf install hugo
|
||||
```
|
||||
|
||||
For the latest version, the Hugo package maintained by [@daftaupe](https://github.com/daftaupe) at Fedora Copr is recommended:
|
||||
|
||||
|
|
@ -530,7 +551,9 @@ sudo eopkg install hugo
|
|||
|
||||
OpenBSD provides a package for Hugo via `pkg_add`:
|
||||
|
||||
doas pkg_add hugo
|
||||
```
|
||||
doas pkg_add hugo
|
||||
```
|
||||
|
||||
|
||||
## Upgrade Hugo
|
||||
|
|
@ -551,6 +574,7 @@ Now that you've installed Hugo, read the [Quick Start guide][quickstart] and exp
|
|||
[dep]: https://github.com/golang/dep
|
||||
[highlight shortcode]: /content-management/shortcodes/#highlight
|
||||
[installgit]: https://git-scm.com/
|
||||
[GCC]: http://www.mingw.org/
|
||||
[installgo]: https://golang.org/dl/
|
||||
[linuxbrew]: https://docs.brew.sh/Homebrew-on-Linux
|
||||
[quickstart]: /getting-started/quick-start/
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue