This adds documentation to the new configDir/Environment logic from .53 (#729)

Adds a config entry to Directory Structure
Adds a Hugo.Environment entry to variables/hugo
Edit the configuration page to wrap first part under a Configuration File heading and introduce a second heading, Configuration Directory to present the feature.
This commit is contained in:
Regis Philibert 2019-01-22 14:27:14 -05:00 committed by GitHub
parent 7cff379f58
commit b922ae7d55
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 46 additions and 3 deletions

View File

@ -18,6 +18,9 @@ aliases: [/overview/source-directory/,/overview/configuration/]
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.
@ -35,6 +38,37 @@ hugo --config a.toml,b.toml,c.toml
Multiple site config files can be specified as a comma-separated string to the `--config` switch.
{{% /note %}}
TODO: distinct config.toml and others (the root object files)
## Configuration Directory
In addition to using a single site config file, one can use the `configDir` directory (default to `config/`) to maintain easier organization and environment specific settings.
- Each file represents a configuration root object, such as `Params`, `Menus`, `Languages` etc...
- Each directory holds a group of files containing settings unique to an environment.
- Files can be localized to become language specific.
```
config
├── _default
│ ├── config.toml
│ ├── languages.toml
│ ├── menus.en.toml
│ ├── menus.zh.toml
│ └── params.toml
├── staging
│ ├── config.toml
│ └── params.toml
└── production
├── config.toml
└── params.toml
```
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.
{{% note %}}
Default environments are __development__ with `hugo serve` and __production__ with `hugo`.
{{%/ note %}}
## All Configuration Settings
The following is the full list of Hugo-defined variables with their default

View File

@ -28,7 +28,7 @@ Running the `hugo new site` generator from the command line will create a direct
.
├── archetypes
├── assets
├── config.toml
├── config
├── content
├── data
├── layouts
@ -48,8 +48,12 @@ By default, Hugo will create new content files with at least `date`, `title` (in
[`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.
[`config.toml`](/getting-started/configuration/)
: Every Hugo project should have a configuration file in TOML, YAML, or JSON format at the 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.
[`config`](/getting-started/configuration/)
: Hugo ships with a large number of [configuration directives](https://gohugo.io/getting-started/configuration/#all-variables-yaml).
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.
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.
[`content`][]
: All content for your website will live inside this directory. Each top-level folder in Hugo is considered a [content section][]. For example, if your site has three main sections---`blog`, `articles`, and `tutorials`---you will have three directories at `content/blog`, `content/articles`, and `content/tutorials`. Hugo uses sections to assign default [content types][].

View File

@ -27,12 +27,17 @@ It contains the following fields:
.Hugo.Version
: the current version of the Hugo binary you are using e.g. `0.13-DEV`<br>
.Hugo.Environment
: the current running environment as defined through the `--environment` cli tag.
.Hugo.CommitHash
: the git commit hash of the current Hugo binary e.g. `0e8bed9ccffba0df554728b46c5bbf6d78ae5247`
.Hugo.BuildDate
: the compile date of the current Hugo binary formatted with RFC 3339 e.g. `2002-10-02T10:00:00-05:00`<br>
{{% note "Use the Hugo Generator Tag" %}}
We highly recommend using `.Hugo.Generator` in your website's `<head>`. `.Hugo.Generator` is included by default in all themes hosted on [themes.gohugo.io](http://themes.gohugo.io). The generator tag allows the Hugo team to track the usage and popularity of Hugo.
{{% /note %}}