From 261a2eee013112586092f728e5b41179a4a788ae Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ren=C3=A9=20Ribaud?= <uggla@free.fr>
Date: Sun, 16 Aug 2020 18:25:52 +0200
Subject: [PATCH] Docs/configuration update (#1126)

* Update configuration documentation

- Attempt to split the configuration file into sections to make it more readable and
  avoid configuration mistakes (#1056).
- Move translation instructions to the right part.
- Add a bit more explanations to the extra section.

* Take into account @Keats feedbacks

* Remove short notice about translation usage

- A i18n page should be created to better explain it.
---
 .../getting-started/configuration.md          | 46 ++++++++++++-------
 1 file changed, 29 insertions(+), 17 deletions(-)

diff --git a/docs/content/documentation/getting-started/configuration.md b/docs/content/documentation/getting-started/configuration.md
index 581b1c6a..b4368323 100644
--- a/docs/content/documentation/getting-started/configuration.md
+++ b/docs/content/documentation/getting-started/configuration.md
@@ -4,14 +4,22 @@ weight = 40
 +++
 
 The default configuration is sufficient to get Zola running locally but not more than that.
-It follows the philosophy of paying for only what you need; almost everything is turned off by default.
+It follows the philosophy of paying for only what you need, almost everything is turned off by default.
 
 To change the configuration, edit the `config.toml` file.
 If you are not familiar with TOML, have a look at [the TOML spec](https://github.com/toml-lang/toml).
 
-Only the `base_url` variable is mandatory; everything else is optional. All configuration variables
-used by Zola as well as their default values are listed below:
+⚠️ If you add keys to your `config.toml`, you must pay attention to which toml section it belongs to.
 
+Here are the current `config.toml` sections:
+1. main (unnamed)
+2. link_checker
+3. slugify
+4. translations
+5. extra
+
+**Only the `base_url` variable is mandatory**. Everything else is optional. All configuration variables
+used by Zola as well as their default values are listed below:
 
 ```toml
 # The base URL of the site; the only required configuration variable.
@@ -90,18 +98,6 @@ ignored_content = []
 # A list of directories used to search for additional `.sublime-syntax` files.
 extra_syntaxes = []
 
-# Optional translation object. The key if present should be a language code.
-# Example:
-#     default_language = "fr"
-#
-#     [translations]
-#     [translations.fr]
-#     title = "Un titre"
-#
-#     [translations.en]
-#     title = "A title"
-
-
 # Configuration of the link checker.
 [link_checker]
 # Skip link checking for external URLs that start with these prefixes
@@ -121,11 +117,27 @@ paths = "on"
 taxonomies = "on"
 anchors = "on"
 
-# Optional translation object. Keys should be language codes.
+# Optional translation object. The key if present should be a language code.
+# Example:
+#     default_language = "fr"
+#
+#     [translations]
+#     [translations.fr]
+#     title = "Un titre"
+#
+#     [translations.en]
+#     title = "A title"
+#
 [translations]
 
 # You can put any kind of data here. The data
-# will be accessible in all templates.
+# will be accessible in all templates
+# Example:
+#     [extra]
+#     author = "Famous author"
+#
+# author value will be available using {{ config.extra.author }} in templates
+#
 [extra]
 ```