From b922ae7d55927abffefe4abcb97c77d8cfbe7001 Mon Sep 17 00:00:00 2001
From: Regis Philibert <login@regisphilibert.com>
Date: Tue, 22 Jan 2019 14:27:14 -0500
Subject: [PATCH] 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.
---
 content/en/getting-started/configuration.md   | 34 +++++++++++++++++++
 .../en/getting-started/directory-structure.md | 10 ++++--
 content/en/variables/hugo.md                  |  5 +++
 3 files changed, 46 insertions(+), 3 deletions(-)

diff --git a/content/en/getting-started/configuration.md b/content/en/getting-started/configuration.md
index a2bc68fd8..b37fa48e7 100644
--- a/content/en/getting-started/configuration.md
+++ b/content/en/getting-started/configuration.md
@@ -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
diff --git a/content/en/getting-started/directory-structure.md b/content/en/getting-started/directory-structure.md
index bf06dc538..4842409d2 100644
--- a/content/en/getting-started/directory-structure.md
+++ b/content/en/getting-started/directory-structure.md
@@ -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][].
diff --git a/content/en/variables/hugo.md b/content/en/variables/hugo.md
index c0c5c9601..a563831ff 100644
--- a/content/en/variables/hugo.md
+++ b/content/en/variables/hugo.md
@@ -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 %}}