From 9aedb926989201a8767db44ffa67a3d1f8a655b0 Mon Sep 17 00:00:00 2001
From: Kaushal Modi <kaushal.modi@gmail.com>
Date: Tue, 22 May 2018 11:47:44 -0400
Subject: [PATCH] Add examples for removing default taxonomies

Also:

- Use "site config" phrase consistently in the whole document.
- Use code-toggle shortcode where needed

Fixes https://github.com/gohugoio/hugoDocs/issues/491
---
 content/en/content-management/taxonomies.md | 39 ++++++++++++++++-----
 1 file changed, 31 insertions(+), 8 deletions(-)

diff --git a/content/en/content-management/taxonomies.md b/content/en/content-management/taxonomies.md
index 287c6f899..1d9ea15a2 100644
--- a/content/en/content-management/taxonomies.md
+++ b/content/en/content-management/taxonomies.md
@@ -82,15 +82,23 @@ Moonrise Kingdom            <- Value
     ...
 ```
 
-## Hugo Taxonomy Defaults
+## Hugo Taxonomy Defaults {#default-taxonomies}
 
 Hugo natively supports taxonomies.
 
-Without adding a single line to your site's configuration file, Hugo will automatically create taxonomies for `tags` and `categories`. If you do not want Hugo to create any taxonomies, set `disableKinds` in your site's configuration to the following:
+Without adding a single line to your [site config][config] file, Hugo will automatically create taxonomies for `tags` and `categories`. That would be same as manually [configuring your taxonomies](#configuring-taxonomies) as below:
 
-```
+{{< code-toggle copy="false" >}}
+[taxonomies]
+  tag = "tags"
+  category = "categories"
+{{</ code-toggle >}}
+
+If you do not want Hugo to create any taxonomies, set `disableKinds` in your [site config][config] to the following:
+
+{{< code-toggle copy="false" >}}
 disableKinds = ["taxonomy","taxonomyTerm"]
-```
+{{</ code-toggle >}}
 
 ### Default Destinations
 
@@ -99,11 +107,15 @@ When taxonomies are used---and [taxonomy templates][] are provided---Hugo will a
 * A single page at `example.com/categories/` that lists all the [terms within the taxonomy][]
 * [Individual taxonomy list pages][taxonomy templates] (e.g., `/categories/development/`) for each of the terms that shows a listing of all pages marked as part of that taxonomy within any content file's [front matter][]
 
-## Configure Taxonomies
+## Configure Taxonomies {#configuring-taxonomies}
 
-Taxonomies must be defined in your [website configuration][config] before they can be used throughout the site. You need to provide both the plural and singular labels for each taxonomy. For example, `singular key = "plural value"` for TOML and `singular key: "plural value"` for YAML.
+Custom taxonomies other than the [defaults](#default-taxonomies) must be defined in your [site config][config] before they can be used throughout the site. You need to provide both the plural and singular labels for each taxonomy. For example, `singular key = "plural value"` for TOML and `singular key: "plural value"` for YAML.
 
-### Example: Taxonomy Configuration
+### Example: Adding a custom taxonomy named "series"
+
+{{% note %}}
+While adding custom taxonomies, you need to put in the default taxonomies too, _if you want to keep them_.
+{{% /note %}}
 
 {{< code-toggle copy="false" >}}
 [taxonomies]
@@ -112,11 +124,22 @@ Taxonomies must be defined in your [website configuration][config] before they c
   series = "series"
 {{</ code-toggle >}}
 
+### Example: Removing default taxonomies
+
+If you want to have just the default `tags` taxonomy, and remove the `categories` taxonomy for your site, you can do so my modifying the `taxonomies` value in your [site config][config].
+
+{{< code-toggle copy="false" >}}
+[taxonomies]
+  tag = "tags"
+{{</ code-toggle >}}
+
+If you want to disable all taxonomies altogether, see the use of `disableKinds` in [Hugo Taxonomy Defaults](#default-taxonomies).
+
 ### Preserve Taxonomy Values
 
 By default, taxonomy names are normalized.
 
-Therefore, if you want to have a taxonomy term with special characters such as `Gérard Depardieu` instead of `Gerard Depardieu`, set the value for `preserveTaxonomyNames` to `true` in your [site configuration][config]. Hugo will then preserve special characters in taxonomy values but will still title-ize the values for titles and normalize them in URLs.
+Therefore, if you want to have a taxonomy term with special characters such as `Gérard Depardieu` instead of `Gerard Depardieu`, set the value for `preserveTaxonomyNames` to `true` in your [site config][config]. Hugo will then preserve special characters in taxonomy values but will still title-ize the values for titles and normalize them in URLs.
 
 Note that if you use `preserveTaxonomyNames` and intend to manually construct URLs to the archive pages, you will need to pass the taxonomy values through the [`urlize` template function][].