From 55d469f327dab9c7f00827289b01f9de5b775ca4 Mon Sep 17 00:00:00 2001
From: Leonardo Galli <leonardo.galli@bluewin.ch>
Date: Fri, 15 Jun 2018 22:46:02 +0200
Subject: [PATCH 01/13] Initial addition of nested categories

---
 lib/jazzy/doc_builder.rb                      | 35 +++++++++++++++++
 lib/jazzy/source_declaration.rb               |  2 +
 lib/jazzy/sourcekitten.rb                     | 38 +++++++++++++------
 .../themes/fullwidth/templates/doc.mustache   |  3 ++
 .../themes/fullwidth/templates/nav.mustache   | 11 +-----
 .../fullwidth/templates/nav_section.mustache  | 15 ++++++++
 .../fullwidth/templates/subsection.mustache   |  5 +++
 .../themes/fullwidth/templates/tasks.mustache |  1 +
 8 files changed, 88 insertions(+), 22 deletions(-)
 create mode 100644 lib/jazzy/themes/fullwidth/templates/nav_section.mustache
 create mode 100644 lib/jazzy/themes/fullwidth/templates/subsection.mustache

diff --git a/lib/jazzy/doc_builder.rb b/lib/jazzy/doc_builder.rb
index 1eb59892f..6090b981a 100644
--- a/lib/jazzy/doc_builder.rb
+++ b/lib/jazzy/doc_builder.rb
@@ -31,6 +31,7 @@ def self.prepare_output_dir(output_dir, clean)
     #                     section names & child names & URLs
     def self.doc_structure_for_docs(docs)
       docs.map do |doc|
+        puts doc.url
         children = doc.children
                       .sort_by { |c| [c.nav_order, c.name, c.usr || ''] }
                       .flat_map do |child|
@@ -42,10 +43,14 @@ def self.doc_structure_for_docs(docs)
               { name: "– #{sub_child.name}", url: sub_child.url }
             end
         end
+
+        subsections = doc_structure_for_docs(doc.subsections.sort_by { |c| [c.nav_order, c.name, c.usr || ''] })
         {
           section: doc.name,
           url: doc.url,
           children: children,
+          subsections: subsections,
+          level: doc.level,
         }
       end
     end
@@ -105,6 +110,13 @@ def self.each_doc(output_dir, docs, &block)
           doc.children,
           &block
         )
+        if doc.subsections != nil
+          each_doc(
+            output_dir,
+            doc.subsections,
+            &block
+          )
+        end
       end
     end
 
@@ -383,6 +395,26 @@ def self.render_tasks(source_module, children)
       end
     end
 
+    def self.render_subsections(subsections)
+      subsections.map do |subsection|
+        overview = (subsection.abstract || '') + (subsection.discussion || '')
+        alternative_abstract = subsection.alternative_abstract
+        if alternative_abstract
+          overview = render(subsection, alternative_abstract) + overview
+        end
+        subsubsections = []
+        if subsection.subsections != nil
+          subsubsections = render_subsections(subsection.subsections)
+        end
+        {
+          name: subsection.name,
+          overview: overview,
+          subsections: subsubsections,
+          level: subsection.level,
+        }
+      end
+    end
+
     # rubocop:disable Metrics/MethodLength
     # Build Mustache document from single parsed doc
     # @param [Config] options Build options
@@ -413,6 +445,9 @@ def self.document(source_module, doc_model, path_to_root)
       doc[:overview] = overview
       doc[:structure] = source_module.doc_structure
       doc[:tasks] = render_tasks(source_module, doc_model.children)
+      if doc_model.subsections != nil
+        doc[:subsections] = render_subsections(doc_model.subsections)
+      end
       doc[:module_name] = source_module.name
       doc[:author_name] = source_module.author_name
       doc[:github_url] = source_module.github_url
diff --git a/lib/jazzy/source_declaration.rb b/lib/jazzy/source_declaration.rb
index 94c9fc46e..29850c177 100644
--- a/lib/jazzy/source_declaration.rb
+++ b/lib/jazzy/source_declaration.rb
@@ -99,6 +99,8 @@ def display_other_language_declaration
     attr_accessor :end_line
     attr_accessor :nav_order
     attr_accessor :url_name
+    attr_accessor :level
+    attr_accessor :subsections
 
     def alternative_abstract
       if file = alternative_abstract_file
diff --git a/lib/jazzy/sourcekitten.rb b/lib/jazzy/sourcekitten.rb
index 046cfae43..a5184f9fa 100644
--- a/lib/jazzy/sourcekitten.rb
+++ b/lib/jazzy/sourcekitten.rb
@@ -68,19 +68,26 @@ def self.group_docs(docs)
       custom_categories + type_categories + uncategorized
     end
 
-    def self.group_custom_categories(docs)
-      group = Config.instance.custom_categories.map do |category|
-        children = category['children'].flat_map do |name|
-          docs_with_name, docs = docs.partition { |doc| doc.name == name }
-          if docs_with_name.empty?
-            STDERR.puts 'WARNING: No documented top-level declarations match ' \
-                        "name \"#{name}\" specified in categories file"
+    def self.group_custom_categories(docs, categories = nil, level = 1)
+      categories ||= Config.instance.custom_categories
+      group = categories.map do |category|
+        children = category['children'].flat_map do |child|
+          if child.is_a?(Hash)
+            docs_with_name, docs = group_custom_categories(docs, [child], level + 1)
+            docs_with_name
+          else
+            docs_with_name, docs = docs.partition { |doc| doc.name == child }
+            if docs_with_name.empty?
+              STDERR.puts 'WARNING: No documented top-level declarations match ' \
+                          "name \"#{child}\" specified in categories file"
+            end
+            docs_with_name
           end
-          docs_with_name
         end
         # Category config overrides alphabetization
         children.each.with_index { |child, i| child.nav_order = i }
-        make_group(children, category['name'], '')
+        subsections, children = children.partition { |c| c.type == SourceDeclaration::Type.overview }
+        make_group(children, category['name'], '', nil, level, subsections)
       end
       [group.compact, docs]
     end
@@ -98,7 +105,7 @@ def self.group_type_categories(docs, type_category_prefix)
       [group.compact, docs]
     end
 
-    def self.make_group(group, name, abstract, url_name = nil)
+    def self.make_group(group, name, abstract, url_name = nil, level = nil, subsections = nil)
       group.reject! { |doc| doc.name.empty? }
       unless group.empty?
         SourceDeclaration.new.tap do |sd|
@@ -107,6 +114,8 @@ def self.make_group(group, name, abstract, url_name = nil)
           sd.url_name = url_name
           sd.abstract = Markdown.render(abstract)
           sd.children = group
+          sd.level    = level
+          sd.subsections = subsections
         end
       end
     end
@@ -126,13 +135,18 @@ def self.sanitize_filename(doc)
     # @return [Hash] input docs with URLs
     def self.make_doc_urls(docs)
       docs.each do |doc|
-        if !doc.parent_in_docs || doc.children.count > 0
+        if !doc.parent_in_docs || doc.children.count > 0 || (doc.subsections != nil && doc.subsections.count > 0)
           # Create HTML page for this doc if it has children or is root-level
           doc.url = (
             subdir_for_doc(doc) +
             [sanitize_filename(doc) + '.html']
           ).join('/')
-          doc.children = make_doc_urls(doc.children)
+          if doc.children.count > 0
+            doc.children = make_doc_urls(doc.children)
+          end
+          if (doc.subsections != nil && doc.subsections.count > 0)
+            doc.subsections = make_doc_urls(doc.subsections)
+          end
         else
           # Don't create HTML page for this doc if it doesn't have children
           # Instead, make its link a hash-link on its parent's page
diff --git a/lib/jazzy/themes/fullwidth/templates/doc.mustache b/lib/jazzy/themes/fullwidth/templates/doc.mustache
index 6af90fbaf..c2ef9d491 100644
--- a/lib/jazzy/themes/fullwidth/templates/doc.mustache
+++ b/lib/jazzy/themes/fullwidth/templates/doc.mustache
@@ -45,6 +45,9 @@
               </div>
             {{/declaration}}
             {{{overview}}}
+            {{#subsections}}
+              {{> subsection}}
+            {{/subsections}}
           </div>
         </section>
 
diff --git a/lib/jazzy/themes/fullwidth/templates/nav.mustache b/lib/jazzy/themes/fullwidth/templates/nav.mustache
index d8fe9e02c..f0542bf0b 100644
--- a/lib/jazzy/themes/fullwidth/templates/nav.mustache
+++ b/lib/jazzy/themes/fullwidth/templates/nav.mustache
@@ -1,16 +1,7 @@
 <nav class="navigation">
   <ul class="nav-groups">
     {{#structure}}
-    <li class="nav-group-name">
-      <a class="nav-group-name-link" href="{{path_to_root}}{{url}}">{{section}}</a>
-      <ul class="nav-group-tasks">
-        {{#children}}
-        <li class="nav-group-task">
-          <a class="nav-group-task-link" href="{{path_to_root}}{{url}}">{{name}}</a>
-        </li>
-        {{/children}}
-      </ul>
-    </li>
+      {{> nav_section}}
     {{/structure}}
   </ul>
 </nav>
diff --git a/lib/jazzy/themes/fullwidth/templates/nav_section.mustache b/lib/jazzy/themes/fullwidth/templates/nav_section.mustache
new file mode 100644
index 000000000..7dfbe3c35
--- /dev/null
+++ b/lib/jazzy/themes/fullwidth/templates/nav_section.mustache
@@ -0,0 +1,15 @@
+<li class="nav-group-name">
+  <a class="nav-group-name-link" href="{{path_to_root}}{{url}}"><h{{level}}>{{section}}</h{{level}}></a>
+  <ul class="nav-group-tasks">
+    {{#children}}
+    <li class="nav-group-task">
+      <a class="nav-group-task-link" href="{{path_to_root}}{{url}}">{{name}}</a>
+    </li>
+    {{/children}}
+  </ul>
+  <ul class="nav-groups">
+    {{#subsections}}
+      {{> nav_section}}
+    {{/subsections}}
+  </ul>
+</li>
diff --git a/lib/jazzy/themes/fullwidth/templates/subsection.mustache b/lib/jazzy/themes/fullwidth/templates/subsection.mustache
new file mode 100644
index 000000000..912545531
--- /dev/null
+++ b/lib/jazzy/themes/fullwidth/templates/subsection.mustache
@@ -0,0 +1,5 @@
+<h{{level}}>{{name}}</h{{level}}>
+{{{overview}}}
+{{#subsections}}
+  {{> subsection}}
+{{/subsections}}
diff --git a/lib/jazzy/themes/fullwidth/templates/tasks.mustache b/lib/jazzy/themes/fullwidth/templates/tasks.mustache
index 16f65e096..751c6cc7a 100644
--- a/lib/jazzy/themes/fullwidth/templates/tasks.mustache
+++ b/lib/jazzy/themes/fullwidth/templates/tasks.mustache
@@ -7,3 +7,4 @@
   </div>
 </section>
 {{/tasks.count}}
+{{structure}}

From 0c899aceef886910d15e187e8e3a3af6a5dd94d6 Mon Sep 17 00:00:00 2001
From: Leonardo Galli <leonardo.galli@bluewin.ch>
Date: Sat, 30 Jun 2018 15:56:02 +0200
Subject: [PATCH 02/13] Moved subsections back to the children property.

---
 lib/jazzy/doc_builder.rb                      | 31 ++++++++++--------
 lib/jazzy/sourcekitten.rb                     |  7 ++--
 .../themes/fullwidth/templates/doc.mustache   |  5 +--
 .../fullwidth/templates/nav_section.mustache  | 16 +++++-----
 .../fullwidth/templates/subsection.mustache   | 32 ++++++++++++++++---
 .../themes/fullwidth/templates/tasks.mustache |  5 ++-
 6 files changed, 60 insertions(+), 36 deletions(-)

diff --git a/lib/jazzy/doc_builder.rb b/lib/jazzy/doc_builder.rb
index 6090b981a..56a94562f 100644
--- a/lib/jazzy/doc_builder.rb
+++ b/lib/jazzy/doc_builder.rb
@@ -35,22 +35,26 @@ def self.doc_structure_for_docs(docs)
         children = doc.children
                       .sort_by { |c| [c.nav_order, c.name, c.usr || ''] }
                       .flat_map do |child|
-          # FIXME: include arbitrarily nested extensible types
-          [{ name: child.name, url: child.url }] +
-            Array(child.children.select do |sub_child|
-              sub_child.type.swift_extensible? || sub_child.type.extension?
-            end).map do |sub_child|
-              { name: "– #{sub_child.name}", url: sub_child.url }
-            end
+          if child.type == SourceDeclaration::Type.overview
+            doc_structure_for_docs([child])
+          else
+            # FIXME: include arbitrarily nested extensible types
+            [{ name: child.name, url: child.url, child: true }] +
+              Array(child.children.select do |sub_child|
+                sub_child.type.swift_extensible? || sub_child.type.extension?
+              end).map do |sub_child|
+                { name: "– #{sub_child.name}", url: sub_child.url, child: true }
+              end
+          end
         end
 
-        subsections = doc_structure_for_docs(doc.subsections.sort_by { |c| [c.nav_order, c.name, c.usr || ''] })
+        #subsections = doc_structure_for_docs(doc.subsections.sort_by { |c| [c.nav_order, c.name, c.usr || ''] })
         {
           section: doc.name,
           url: doc.url,
           children: children,
-          subsections: subsections,
-          level: doc.level,
+          #subsections: subsections,
+          level: doc.level || 1,
         }
       end
     end
@@ -409,7 +413,8 @@ def self.render_subsections(subsections)
         {
           name: subsection.name,
           overview: overview,
-          subsections: subsubsections,
+          uid: URI.encode(subsection.name),
+          url: subsection.url,
           level: subsection.level,
         }
       end
@@ -445,9 +450,7 @@ def self.document(source_module, doc_model, path_to_root)
       doc[:overview] = overview
       doc[:structure] = source_module.doc_structure
       doc[:tasks] = render_tasks(source_module, doc_model.children)
-      if doc_model.subsections != nil
-        doc[:subsections] = render_subsections(doc_model.subsections)
-      end
+      doc[:subsections] = render_subsections(doc_model.children.select { |c| c.type == SourceDeclaration::Type.overview })
       doc[:module_name] = source_module.name
       doc[:author_name] = source_module.author_name
       doc[:github_url] = source_module.github_url
diff --git a/lib/jazzy/sourcekitten.rb b/lib/jazzy/sourcekitten.rb
index a5184f9fa..cb155da18 100644
--- a/lib/jazzy/sourcekitten.rb
+++ b/lib/jazzy/sourcekitten.rb
@@ -86,8 +86,8 @@ def self.group_custom_categories(docs, categories = nil, level = 1)
         end
         # Category config overrides alphabetization
         children.each.with_index { |child, i| child.nav_order = i }
-        subsections, children = children.partition { |c| c.type == SourceDeclaration::Type.overview }
-        make_group(children, category['name'], '', nil, level, subsections)
+        #subsections, children = children.partition { |c| c.type == SourceDeclaration::Type.overview }
+        make_group(children, category['name'], '', nil, level)
       end
       [group.compact, docs]
     end
@@ -105,7 +105,7 @@ def self.group_type_categories(docs, type_category_prefix)
       [group.compact, docs]
     end
 
-    def self.make_group(group, name, abstract, url_name = nil, level = nil, subsections = nil)
+    def self.make_group(group, name, abstract, url_name = nil, level = nil)
       group.reject! { |doc| doc.name.empty? }
       unless group.empty?
         SourceDeclaration.new.tap do |sd|
@@ -115,7 +115,6 @@ def self.make_group(group, name, abstract, url_name = nil, level = nil, subsecti
           sd.abstract = Markdown.render(abstract)
           sd.children = group
           sd.level    = level
-          sd.subsections = subsections
         end
       end
     end
diff --git a/lib/jazzy/themes/fullwidth/templates/doc.mustache b/lib/jazzy/themes/fullwidth/templates/doc.mustache
index c2ef9d491..b5d56106e 100644
--- a/lib/jazzy/themes/fullwidth/templates/doc.mustache
+++ b/lib/jazzy/themes/fullwidth/templates/doc.mustache
@@ -45,14 +45,11 @@
               </div>
             {{/declaration}}
             {{{overview}}}
-            {{#subsections}}
-              {{> subsection}}
-            {{/subsections}}
           </div>
         </section>
 
         {{> tasks}}
-
+        
       </article>
     </div>
     {{> footer}}
diff --git a/lib/jazzy/themes/fullwidth/templates/nav_section.mustache b/lib/jazzy/themes/fullwidth/templates/nav_section.mustache
index 7dfbe3c35..0547b3712 100644
--- a/lib/jazzy/themes/fullwidth/templates/nav_section.mustache
+++ b/lib/jazzy/themes/fullwidth/templates/nav_section.mustache
@@ -2,14 +2,14 @@
   <a class="nav-group-name-link" href="{{path_to_root}}{{url}}"><h{{level}}>{{section}}</h{{level}}></a>
   <ul class="nav-group-tasks">
     {{#children}}
-    <li class="nav-group-task">
-      <a class="nav-group-task-link" href="{{path_to_root}}{{url}}">{{name}}</a>
-    </li>
-    {{/children}}
-  </ul>
-  <ul class="nav-groups">
-    {{#subsections}}
+    {{#child}}
+      <li class="nav-group-task">
+        <a class="nav-group-task-link" href="{{path_to_root}}{{url}}">{{name}}</a>
+      </li>
+    {{/child}}
+    {{^child}}
       {{> nav_section}}
-    {{/subsections}}
+    {{/child}}
+    {{/children}}
   </ul>
 </li>
diff --git a/lib/jazzy/themes/fullwidth/templates/subsection.mustache b/lib/jazzy/themes/fullwidth/templates/subsection.mustache
index 912545531..3f0767995 100644
--- a/lib/jazzy/themes/fullwidth/templates/subsection.mustache
+++ b/lib/jazzy/themes/fullwidth/templates/subsection.mustache
@@ -1,5 +1,27 @@
-<h{{level}}>{{name}}</h{{level}}>
-{{{overview}}}
-{{#subsections}}
-  {{> subsection}}
-{{/subsections}}
+<div class="task-group">
+  <div class="task-name-container">
+    <a name="/{{uid}}"></a>
+    <a name="//apple_ref/{{language_stub}}/Section/{{name}}" class="dashAnchor"></a>
+    <span>
+      <a class="token" href="#/{{uid}}">
+        <h3 class="section-name">{{name}}</h3>
+      </a>
+    </span>
+  </div>
+
+  <div class="height-container">
+    <div class="pointer-container"></div>
+    <section class="section">
+      <div class="pointer"></div>
+      {{#overview}}
+      <div class="abstract">
+        {{{overview}}}
+        {{#url}}
+        <a href="{{{path_to_root}}}{{{url}}}" class="slightly-smaller">See more</a>
+        {{/url}}
+      </div>
+      {{/overview}}
+    </section>
+
+  </div>
+</div>
diff --git a/lib/jazzy/themes/fullwidth/templates/tasks.mustache b/lib/jazzy/themes/fullwidth/templates/tasks.mustache
index 751c6cc7a..46d5091d6 100644
--- a/lib/jazzy/themes/fullwidth/templates/tasks.mustache
+++ b/lib/jazzy/themes/fullwidth/templates/tasks.mustache
@@ -4,7 +4,10 @@
     {{#tasks}}
     {{> task}}
     {{/tasks}}
+
+    {{#subsections}}
+      {{> subsection}}
+    {{/subsections}}
   </div>
 </section>
 {{/tasks.count}}
-{{structure}}

From 14b567bb440ccfc88e1958e27f539dbb65e3cdbb Mon Sep 17 00:00:00 2001
From: Leonardo Galli <leonardo.galli@bluewin.ch>
Date: Sat, 7 Jul 2018 12:23:27 +0200
Subject: [PATCH 03/13] Moved categories to their own class and fixed up the
 css.

---
 lib/jazzy/doc_builder.rb                      | 25 +++---
 lib/jazzy/source_category.rb                  | 78 +++++++++++++++++++
 lib/jazzy/source_declaration/type.rb          |  9 +++
 lib/jazzy/sourcekitten.rb                     | 63 +--------------
 .../fullwidth/assets/css/jazzy.css.scss       | 38 ++++++++-
 .../fullwidth/templates/nav_section.mustache  |  8 +-
 .../fullwidth/templates/subsection.mustache   |  8 ++
 7 files changed, 149 insertions(+), 80 deletions(-)
 create mode 100644 lib/jazzy/source_category.rb

diff --git a/lib/jazzy/doc_builder.rb b/lib/jazzy/doc_builder.rb
index 56a94562f..dd67ecf2d 100644
--- a/lib/jazzy/doc_builder.rb
+++ b/lib/jazzy/doc_builder.rb
@@ -31,30 +31,27 @@ def self.prepare_output_dir(output_dir, clean)
     #                     section names & child names & URLs
     def self.doc_structure_for_docs(docs)
       docs.map do |doc|
-        puts doc.url
         children = doc.children
                       .sort_by { |c| [c.nav_order, c.name, c.usr || ''] }
                       .flat_map do |child|
-          if child.type == SourceDeclaration::Type.overview
+          if child.type == SourceDeclaration::Type.category
             doc_structure_for_docs([child])
           else
             # FIXME: include arbitrarily nested extensible types
-            [{ name: child.name, url: child.url, child: true }] +
+            [{ name: child.name, url: child.url, children: nil}] +
               Array(child.children.select do |sub_child|
                 sub_child.type.swift_extensible? || sub_child.type.extension?
               end).map do |sub_child|
-                { name: "– #{sub_child.name}", url: sub_child.url, child: true }
+                { name: "– #{sub_child.name}", url: sub_child.url, children: nil }
               end
           end
         end
 
-        #subsections = doc_structure_for_docs(doc.subsections.sort_by { |c| [c.nav_order, c.name, c.usr || ''] })
         {
           section: doc.name,
           url: doc.url,
           children: children,
-          #subsections: subsections,
-          level: doc.level || 1,
+          level: doc.level,
         }
       end
     end
@@ -399,23 +396,22 @@ def self.render_tasks(source_module, children)
       end
     end
 
-    def self.render_subsections(subsections)
+    def self.render_subsections(subsections, source_module)
       subsections.map do |subsection|
         overview = (subsection.abstract || '') + (subsection.discussion || '')
         alternative_abstract = subsection.alternative_abstract
         if alternative_abstract
           overview = render(subsection, alternative_abstract) + overview
         end
-        subsubsections = []
-        if subsection.subsections != nil
-          subsubsections = render_subsections(subsection.subsections)
-        end
+        tasks = render_tasks(source_module, subsection.children.select { |c| c.type != SourceDeclaration::Type.category })
+
         {
           name: subsection.name,
           overview: overview,
           uid: URI.encode(subsection.name),
           url: subsection.url,
           level: subsection.level,
+          tasks: tasks,
         }
       end
     end
@@ -449,8 +445,9 @@ def self.document(source_module, doc_model, path_to_root)
       doc[:declaration] = doc_model.display_declaration
       doc[:overview] = overview
       doc[:structure] = source_module.doc_structure
-      doc[:tasks] = render_tasks(source_module, doc_model.children)
-      doc[:subsections] = render_subsections(doc_model.children.select { |c| c.type == SourceDeclaration::Type.overview })
+      categories, children = doc_model.children.partition { |c| c.type == SourceDeclaration::Type.category }
+      doc[:tasks] = render_tasks(source_module, children)
+      doc[:subsections] = render_subsections(categories, source_module)
       doc[:module_name] = source_module.name
       doc[:author_name] = source_module.author_name
       doc[:github_url] = source_module.github_url
diff --git a/lib/jazzy/source_category.rb b/lib/jazzy/source_category.rb
new file mode 100644
index 000000000..63b3b46ca
--- /dev/null
+++ b/lib/jazzy/source_category.rb
@@ -0,0 +1,78 @@
+require 'jazzy/source_declaration'
+require 'jazzy/config'
+require 'jazzy/source_mark'
+require 'jazzy/jazzy_markdown'
+
+module Jazzy
+  # Category (group, contents) pages generated by jazzy
+  class SourceCategory < SourceDeclaration
+    extend Config::Mixin
+
+    def initialize(group, name, abstract, url_name, level = 1)
+      super()
+      self.type     = SourceDeclaration::Type.category
+      self.name     = name
+      self.url_name = url_name
+      self.abstract = Markdown.render(abstract)
+      self.children = group
+      self.parameters = []
+      self.mark       = SourceMark.new
+      self.level    = level
+    end
+
+    # Group root-level docs into custom categories or by type
+    def self.group_docs(docs)
+      custom_categories, docs =
+        group_custom_categories(docs, config.custom_categories)
+      type_categories, uncategorized = group_type_categories(
+        docs, custom_categories.any? ? 'Other ' : ''
+      )
+      custom_categories + type_categories + uncategorized
+    end
+
+    def self.group_custom_categories(docs, categories, level = 1)
+      group = categories.map do |category|
+        children = category['children'].flat_map do |child|
+          if child.is_a?(Hash)
+            # Nested category, recurse
+            docs_with_name, docs = group_custom_categories(docs, [child], level + 1)
+          else
+            # Doc name, find it
+            docs_with_name, docs = docs.partition { |doc| doc.name == child }
+            if docs_with_name.empty?
+              STDERR.puts(
+                'WARNING: No documented top-level declarations match ' \
+                "name \"#{child}\" specified in categories file",
+              )
+            end
+          end
+          docs_with_name
+        end
+        # Category config overrides alphabetization
+        children.each.with_index { |child, i| child.nav_order = i }
+        make_group(children, category['name'], '', nil, level)
+      end
+      [group.compact, docs]
+    end
+
+    def self.group_type_categories(docs, type_category_prefix)
+      group = SourceDeclaration::Type.all.map do |type|
+        children, docs = docs.partition { |doc| doc.type == type }
+        make_group(
+          children,
+          type_category_prefix + type.plural_name,
+          "The following #{type.plural_name.downcase} are available globally.",
+          type_category_prefix + type.plural_url_name,
+        )
+      end
+      [group.compact, docs]
+    end
+
+    def self.make_group(group, name, abstract, url_name = nil, level = 1)
+      group.reject! { |doc| doc.name.empty? }
+      unless group.empty?
+        SourceCategory.new(group, name, abstract, url_name, level)
+      end
+    end
+  end
+end
diff --git a/lib/jazzy/source_declaration/type.rb b/lib/jazzy/source_declaration/type.rb
index 5f72ecff3..1d815cff6 100644
--- a/lib/jazzy/source_declaration/type.rb
+++ b/lib/jazzy/source_declaration/type.rb
@@ -129,6 +129,10 @@ def self.overview
         Type.new('Overview')
       end
 
+      def self.category
+        Type.new('Category')
+      end
+
       def hash
         kind.hash
       end
@@ -150,6 +154,11 @@ def ==(other)
           dash: 'Section',
         }.freeze,
 
+        'Category' => {
+          jazzy: nil,
+          dash: 'Section',
+        }.freeze,
+
         # Objective-C
         'sourcekitten.source.lang.objc.decl.unexposed' => {
           jazzy: 'Unexposed',
diff --git a/lib/jazzy/sourcekitten.rb b/lib/jazzy/sourcekitten.rb
index cb155da18..65967573f 100644
--- a/lib/jazzy/sourcekitten.rb
+++ b/lib/jazzy/sourcekitten.rb
@@ -11,6 +11,7 @@
 require 'jazzy/source_declaration'
 require 'jazzy/source_mark'
 require 'jazzy/stats'
+require 'jazzy/source_category'
 
 ELIDED_AUTOLINK_TOKEN = '36f8f5912051ae747ef441d6511ca4cb'.freeze
 
@@ -59,66 +60,6 @@ def self.undocumented_abstract
       ).freeze
     end
 
-    # Group root-level docs by custom categories (if any) and type
-    def self.group_docs(docs)
-      custom_categories, docs = group_custom_categories(docs)
-      type_categories, uncategorized = group_type_categories(
-        docs, custom_categories.any? ? 'Other ' : ''
-      )
-      custom_categories + type_categories + uncategorized
-    end
-
-    def self.group_custom_categories(docs, categories = nil, level = 1)
-      categories ||= Config.instance.custom_categories
-      group = categories.map do |category|
-        children = category['children'].flat_map do |child|
-          if child.is_a?(Hash)
-            docs_with_name, docs = group_custom_categories(docs, [child], level + 1)
-            docs_with_name
-          else
-            docs_with_name, docs = docs.partition { |doc| doc.name == child }
-            if docs_with_name.empty?
-              STDERR.puts 'WARNING: No documented top-level declarations match ' \
-                          "name \"#{child}\" specified in categories file"
-            end
-            docs_with_name
-          end
-        end
-        # Category config overrides alphabetization
-        children.each.with_index { |child, i| child.nav_order = i }
-        #subsections, children = children.partition { |c| c.type == SourceDeclaration::Type.overview }
-        make_group(children, category['name'], '', nil, level)
-      end
-      [group.compact, docs]
-    end
-
-    def self.group_type_categories(docs, type_category_prefix)
-      group = SourceDeclaration::Type.all.map do |type|
-        children, docs = docs.partition { |doc| doc.type == type }
-        make_group(
-          children,
-          type_category_prefix + type.plural_name,
-          "The following #{type.plural_name.downcase} are available globally.",
-          type_category_prefix + type.plural_url_name,
-        )
-      end
-      [group.compact, docs]
-    end
-
-    def self.make_group(group, name, abstract, url_name = nil, level = nil)
-      group.reject! { |doc| doc.name.empty? }
-      unless group.empty?
-        SourceDeclaration.new.tap do |sd|
-          sd.type     = SourceDeclaration::Type.overview
-          sd.name     = name
-          sd.url_name = url_name
-          sd.abstract = Markdown.render(abstract)
-          sd.children = group
-          sd.level    = level
-        end
-      end
-    end
-
     def self.sanitize_filename(doc)
       unsafe_filename = doc.url_name || doc.name
       sanitzation_enabled = Config.instance.use_safe_filenames
@@ -819,7 +760,7 @@ def self.parse(sourcekitten_output, min_acl, skip_undocumented, inject_docs)
         docs = docs.reject { |doc| doc.type.swift_enum_element? }
       end
       ungrouped_docs = docs
-      docs = group_docs(docs)
+      docs = SourceCategory.group_docs(docs)
       make_doc_urls(docs)
       autolink(docs, ungrouped_docs)
       [docs, @stats]
diff --git a/lib/jazzy/themes/fullwidth/assets/css/jazzy.css.scss b/lib/jazzy/themes/fullwidth/assets/css/jazzy.css.scss
index fdba1186b..a13f3fda4 100644
--- a/lib/jazzy/themes/fullwidth/assets/css/jazzy.css.scss
+++ b/lib/jazzy/themes/fullwidth/assets/css/jazzy.css.scss
@@ -320,6 +320,12 @@ pre code {
 .nav-group-tasks {
   margin: $gutter/2 0;
   padding: 0 0 0 $gutter/2;
+
+  .nav-group-name {
+    list-style-type: none;
+    border: 0px;
+    padding: 0px;
+  }
 }
 
 .nav-group-task {
@@ -332,6 +338,24 @@ pre code {
   color: $navigation_task_color;
 }
 
+@mixin nav_heading($font-size: 1.5rem, $margin: 1.0rem 0px 0px 0px) {
+  font-size: $font-size;
+  font-weight: $heading_weight;
+  margin: $margin;
+}
+
+.nav-groups {
+  h1 {
+    @include nav_heading(1.75rem);
+  }
+  h2 {
+    @include nav_heading(1.5rem);
+  }
+  h3 {
+    @include nav_heading(1.25rem);
+  }
+}
+
 // ===========================================================================
 //
 //  Content
@@ -379,6 +403,18 @@ pre code {
   padding-top: 0px;
 }
 
+.nested-tasks {
+  .task-group {
+    margin-top: 10px;
+  }
+}
+
+.nested-tasks-line {
+  border: none;
+  border-top: $gray_border;
+  margin-top: 15px;
+}
+
 .task-name-container {
   a[name] {
     &:before {
@@ -612,4 +648,4 @@ form[role=search] {
   .tt-suggestion.tt-cursor .doc-parent-name {
     color: #fff;
   }
-}
\ No newline at end of file
+}
diff --git a/lib/jazzy/themes/fullwidth/templates/nav_section.mustache b/lib/jazzy/themes/fullwidth/templates/nav_section.mustache
index 0547b3712..4490b9268 100644
--- a/lib/jazzy/themes/fullwidth/templates/nav_section.mustache
+++ b/lib/jazzy/themes/fullwidth/templates/nav_section.mustache
@@ -2,14 +2,14 @@
   <a class="nav-group-name-link" href="{{path_to_root}}{{url}}"><h{{level}}>{{section}}</h{{level}}></a>
   <ul class="nav-group-tasks">
     {{#children}}
-    {{#child}}
+    {{^children.count}}
       <li class="nav-group-task">
         <a class="nav-group-task-link" href="{{path_to_root}}{{url}}">{{name}}</a>
       </li>
-    {{/child}}
-    {{^child}}
+    {{/children.count}}
+    {{#children.count}}
       {{> nav_section}}
-    {{/child}}
+    {{/children.count}}
     {{/children}}
   </ul>
 </li>
diff --git a/lib/jazzy/themes/fullwidth/templates/subsection.mustache b/lib/jazzy/themes/fullwidth/templates/subsection.mustache
index 3f0767995..ea93963be 100644
--- a/lib/jazzy/themes/fullwidth/templates/subsection.mustache
+++ b/lib/jazzy/themes/fullwidth/templates/subsection.mustache
@@ -21,6 +21,14 @@
         {{/url}}
       </div>
       {{/overview}}
+      {{#tasks.count}}
+      <hr class="nested-tasks-line">
+      <div class="nested-tasks">
+        {{#tasks}}
+        {{> task}}
+        {{/tasks}}
+      </div>
+      {{/tasks.count}}
     </section>
 
   </div>

From c9c597e302af284fc15b7f43f3b5f975c22e5bef Mon Sep 17 00:00:00 2001
From: Leonardo Galli <leonardo.galli@bluewin.ch>
Date: Sat, 7 Jul 2018 14:37:40 +0200
Subject: [PATCH 04/13] Updated config file to include hint about nested
 categories. Also added an example with nested categories.

---
 lib/jazzy/config.rb       | 7 ++++++-
 lib/jazzy/sourcekitten.rb | 5 +----
 2 files changed, 7 insertions(+), 5 deletions(-)

diff --git a/lib/jazzy/config.rb b/lib/jazzy/config.rb
index 28ac96511..035b8ed50 100644
--- a/lib/jazzy/config.rb
+++ b/lib/jazzy/config.rb
@@ -310,7 +310,12 @@ def expand_path(path)
       description: ['Custom navigation categories to replace the standard '\
                     '“Classes, Protocols, etc.”', 'Types not explicitly named '\
                     'in a custom category appear in generic groups at the end.',
-                    'Example: https://git.io/v4Bcp'],
+                    'You can add another category in the children array instead '\
+                    'of using a type name, to create subcategories.',
+                    'This can be repeated ad infinitum, provided '\
+                    'your theme supports it.',
+                    'Currently all integrated themes support a maximum of 3 levels.',
+                    'Example: https://git.io/fNvGB'],
       default: []
 
     config_attr :custom_head,
diff --git a/lib/jazzy/sourcekitten.rb b/lib/jazzy/sourcekitten.rb
index 65967573f..bf173c00d 100644
--- a/lib/jazzy/sourcekitten.rb
+++ b/lib/jazzy/sourcekitten.rb
@@ -75,7 +75,7 @@ def self.sanitize_filename(doc)
     # @return [Hash] input docs with URLs
     def self.make_doc_urls(docs)
       docs.each do |doc|
-        if !doc.parent_in_docs || doc.children.count > 0 || (doc.subsections != nil && doc.subsections.count > 0)
+        if !doc.parent_in_docs || doc.children.count > 0
           # Create HTML page for this doc if it has children or is root-level
           doc.url = (
             subdir_for_doc(doc) +
@@ -84,9 +84,6 @@ def self.make_doc_urls(docs)
           if doc.children.count > 0
             doc.children = make_doc_urls(doc.children)
           end
-          if (doc.subsections != nil && doc.subsections.count > 0)
-            doc.subsections = make_doc_urls(doc.subsections)
-          end
         else
           # Don't create HTML page for this doc if it doesn't have children
           # Instead, make its link a hash-link on its parent's page

From d8b2f27596831ff3299b92a4aae60a0736b5149f Mon Sep 17 00:00:00 2001
From: Leonardo Galli <leonardo.galli@bluewin.ch>
Date: Thu, 12 Jul 2018 22:49:21 +0200
Subject: [PATCH 05/13] Fixed rubocop errors, made subcategory urls go to
 subdirectories, tidied up css and fixed a few other things.

---
 lib/jazzy/config.rb                           | 11 ++--
 lib/jazzy/doc_builder.rb                      | 60 ++++++++++---------
 lib/jazzy/source_category.rb                  | 13 ++--
 lib/jazzy/source_declaration.rb               | 14 ++++-
 lib/jazzy/source_declaration/type.rb          | 13 ++--
 lib/jazzy/sourcekitten.rb                     | 10 ++--
 .../fullwidth/assets/css/jazzy.css.scss       | 14 ++---
 .../themes/fullwidth/templates/doc.mustache   |  2 +-
 .../fullwidth/templates/subsection.mustache   |  6 +-
 9 files changed, 79 insertions(+), 64 deletions(-)

diff --git a/lib/jazzy/config.rb b/lib/jazzy/config.rb
index 035b8ed50..b47ed5226 100644
--- a/lib/jazzy/config.rb
+++ b/lib/jazzy/config.rb
@@ -310,11 +310,12 @@ def expand_path(path)
       description: ['Custom navigation categories to replace the standard '\
                     '“Classes, Protocols, etc.”', 'Types not explicitly named '\
                     'in a custom category appear in generic groups at the end.',
-                    'You can add another category in the children array instead '\
-                    'of using a type name, to create subcategories.',
-                    'This can be repeated ad infinitum, provided '\
-                    'your theme supports it.',
-                    'Currently all integrated themes support a maximum of 3 levels.',
+                    'You can add another category in the children array '\
+                    'instead of using a type name, to create ',
+                    'subcategories. This can be repeated ad infinitum, '\
+                    'provided your theme supports it.',
+                    'Currently all integrated themes support a maximum ',
+                    'of 3 levels.',
                     'Example: https://git.io/fNvGB'],
       default: []
 
diff --git a/lib/jazzy/doc_builder.rb b/lib/jazzy/doc_builder.rb
index dd67ecf2d..14e594f17 100644
--- a/lib/jazzy/doc_builder.rb
+++ b/lib/jazzy/doc_builder.rb
@@ -34,16 +34,10 @@ def self.doc_structure_for_docs(docs)
         children = doc.children
                       .sort_by { |c| [c.nav_order, c.name, c.usr || ''] }
                       .flat_map do |child|
-          if child.type == SourceDeclaration::Type.category
+          if child.type.overview?
             doc_structure_for_docs([child])
           else
-            # FIXME: include arbitrarily nested extensible types
-            [{ name: child.name, url: child.url, children: nil}] +
-              Array(child.children.select do |sub_child|
-                sub_child.type.swift_extensible? || sub_child.type.extension?
-              end).map do |sub_child|
-                { name: "– #{sub_child.name}", url: sub_child.url, children: nil }
-              end
+            doc_structure_for_child(child)
           end
         end
 
@@ -56,6 +50,20 @@ def self.doc_structure_for_docs(docs)
       end
     end
 
+    # Generate structure for children of a category in sidebar navigation.
+    # @return [Array] doc structure compromised of
+    #                     name and url of the child as well as
+    #                     any possible nested children.
+    def self.doc_structure_for_child(child)
+      # FIXME: include arbitrarily nested extensible types
+      [{ name: child.name, url: child.url, children: nil }] +
+        Array(child.children.select do |sub_child|
+          sub_child.type.swift_extensible? || sub_child.type.extension?
+        end).map do |sub_child|
+          { name: "– #{sub_child.name}", url: sub_child.url, children: nil }
+        end
+    end
+
     # Build documentation from the given options
     # @param [Config] options
     # @return [SourceModule] the documented source module
@@ -111,13 +119,6 @@ def self.each_doc(output_dir, docs, &block)
           doc.children,
           &block
         )
-        if doc.subsections != nil
-          each_doc(
-            output_dir,
-            doc.subsections,
-            &block
-          )
-        end
       end
     end
 
@@ -398,12 +399,11 @@ def self.render_tasks(source_module, children)
 
     def self.render_subsections(subsections, source_module)
       subsections.map do |subsection|
-        overview = (subsection.abstract || '') + (subsection.discussion || '')
-        alternative_abstract = subsection.alternative_abstract
-        if alternative_abstract
-          overview = render(subsection, alternative_abstract) + overview
-        end
-        tasks = render_tasks(source_module, subsection.children.select { |c| c.type != SourceDeclaration::Type.category })
+        overview = render_overview(subsection)
+        tasks = render_tasks(
+          source_module,
+          subsection.children.reject { |c| c.type.overview? },
+        )
 
         {
           name: subsection.name,
@@ -416,6 +416,15 @@ def self.render_subsections(subsections, source_module)
       end
     end
 
+    def self.render_overview(doc)
+      overview = (doc.abstract || '') + (doc.discussion || '')
+      alternative_abstract = doc.alternative_abstract
+      if alternative_abstract
+        overview = render(doc, alternative_abstract) + overview
+      end
+      overview
+    end
+
     # rubocop:disable Metrics/MethodLength
     # Build Mustache document from single parsed doc
     # @param [Config] options Build options
@@ -428,11 +437,7 @@ def self.document(source_module, doc_model, path_to_root)
         return document_markdown(source_module, doc_model, path_to_root)
       end
 
-      overview = (doc_model.abstract || '') + (doc_model.discussion || '')
-      alternative_abstract = doc_model.alternative_abstract
-      if alternative_abstract
-        overview = render(doc_model, alternative_abstract) + overview
-      end
+      overview = render_overview(doc_model)
 
       doc = Doc.new # Mustache model instance
       doc[:custom_head] = Config.instance.custom_head
@@ -445,7 +450,8 @@ def self.document(source_module, doc_model, path_to_root)
       doc[:declaration] = doc_model.display_declaration
       doc[:overview] = overview
       doc[:structure] = source_module.doc_structure
-      categories, children = doc_model.children.partition { |c| c.type == SourceDeclaration::Type.category }
+      categories, children =
+        doc_model.children.partition { |c| c.type.overview? }
       doc[:tasks] = render_tasks(source_module, children)
       doc[:subsections] = render_subsections(categories, source_module)
       doc[:module_name] = source_module.name
diff --git a/lib/jazzy/source_category.rb b/lib/jazzy/source_category.rb
index 63b3b46ca..0d9bb6a87 100644
--- a/lib/jazzy/source_category.rb
+++ b/lib/jazzy/source_category.rb
@@ -10,14 +10,13 @@ class SourceCategory < SourceDeclaration
 
     def initialize(group, name, abstract, url_name, level = 1)
       super()
-      self.type     = SourceDeclaration::Type.category
+      self.type     = SourceDeclaration::Type.overview
       self.name     = name
       self.url_name = url_name
       self.abstract = Markdown.render(abstract)
       self.children = group
       self.parameters = []
-      self.mark       = SourceMark.new
-      self.level    = level
+      self.level      = level
     end
 
     # Group root-level docs into custom categories or by type
@@ -35,18 +34,18 @@ def self.group_custom_categories(docs, categories, level = 1)
         children = category['children'].flat_map do |child|
           if child.is_a?(Hash)
             # Nested category, recurse
-            docs_with_name, docs = group_custom_categories(docs, [child], level + 1)
+            children, docs = group_custom_categories(docs, [child], level + 1)
           else
             # Doc name, find it
-            docs_with_name, docs = docs.partition { |doc| doc.name == child }
-            if docs_with_name.empty?
+            children, docs = docs.partition { |doc| doc.name == child }
+            if children.empty?
               STDERR.puts(
                 'WARNING: No documented top-level declarations match ' \
                 "name \"#{child}\" specified in categories file",
               )
             end
           end
-          docs_with_name
+          children
         end
         # Category config overrides alphabetization
         children.each.with_index { |child, i| child.nav_order = i }
diff --git a/lib/jazzy/source_declaration.rb b/lib/jazzy/source_declaration.rb
index 29850c177..079dc3ddd 100644
--- a/lib/jazzy/source_declaration.rb
+++ b/lib/jazzy/source_declaration.rb
@@ -45,6 +45,19 @@ def namespace_ancestors
       end
     end
 
+    # Chain of parent_in_docs from top level to self. (Includes self.)
+    def documentation_path
+      documentation_ancestors + [self]
+    end
+
+    def documentation_ancestors
+      if parent_in_docs
+        parent_in_docs.documentation_path
+      else
+        []
+      end
+    end
+
     def fully_qualified_name
       namespace_path.map(&:name).join('.')
     end
@@ -100,7 +113,6 @@ def display_other_language_declaration
     attr_accessor :nav_order
     attr_accessor :url_name
     attr_accessor :level
-    attr_accessor :subsections
 
     def alternative_abstract
       if file = alternative_abstract_file
diff --git a/lib/jazzy/source_declaration/type.rb b/lib/jazzy/source_declaration/type.rb
index 1d815cff6..ea0efbd56 100644
--- a/lib/jazzy/source_declaration/type.rb
+++ b/lib/jazzy/source_declaration/type.rb
@@ -125,12 +125,12 @@ def objc_unexposed?
         kind == 'sourcekitten.source.lang.objc.decl.unexposed'
       end
 
-      def self.overview
-        Type.new('Overview')
+      def overview?
+        Type.overview == self
       end
 
-      def self.category
-        Type.new('Category')
+      def self.overview
+        Type.new('Overview')
       end
 
       def hash
@@ -154,11 +154,6 @@ def ==(other)
           dash: 'Section',
         }.freeze,
 
-        'Category' => {
-          jazzy: nil,
-          dash: 'Section',
-        }.freeze,
-
         # Objective-C
         'sourcekitten.source.lang.objc.decl.unexposed' => {
           jazzy: 'Unexposed',
diff --git a/lib/jazzy/sourcekitten.rb b/lib/jazzy/sourcekitten.rb
index bf173c00d..419bdb3f9 100644
--- a/lib/jazzy/sourcekitten.rb
+++ b/lib/jazzy/sourcekitten.rb
@@ -81,9 +81,7 @@ def self.make_doc_urls(docs)
             subdir_for_doc(doc) +
             [sanitize_filename(doc) + '.html']
           ).join('/')
-          if doc.children.count > 0
-            doc.children = make_doc_urls(doc.children)
-          end
+          doc.children = make_doc_urls(doc.children)
         else
           # Don't create HTML page for this doc if it doesn't have children
           # Instead, make its link a hash-link on its parent's page
@@ -119,8 +117,12 @@ def self.subdir_for_doc(doc)
         # File program elements under top ancestor’s type (Struct, Class, etc.)
         [top_level_decl.type.plural_url_name] +
           doc.namespace_ancestors.map(&:name)
-      else
+      elsif doc.type == SourceDeclaration::Type.overview
         # Categories live in their own directory
+        # But subcategories live in a directory named after their parent
+        doc.documentation_ancestors.map(&:name)
+      else
+        # Anything else
         []
       end
     end
diff --git a/lib/jazzy/themes/fullwidth/assets/css/jazzy.css.scss b/lib/jazzy/themes/fullwidth/assets/css/jazzy.css.scss
index a13f3fda4..eab098db9 100644
--- a/lib/jazzy/themes/fullwidth/assets/css/jazzy.css.scss
+++ b/lib/jazzy/themes/fullwidth/assets/css/jazzy.css.scss
@@ -338,21 +338,21 @@ pre code {
   color: $navigation_task_color;
 }
 
-@mixin nav_heading($font-size: 1.5rem, $margin: 1.0rem 0px 0px 0px) {
+@mixin nav_heading($font-size: 1.5rem, $font-weight: 400, $margin: 1.0rem 0px 0px 0px) {
   font-size: $font-size;
-  font-weight: $heading_weight;
+  font-weight: $font-weight;
   margin: $margin;
 }
 
 .nav-groups {
   h1 {
-    @include nav_heading(1.75rem);
+    @include nav_heading(1.15em, 600);
   }
   h2 {
-    @include nav_heading(1.5rem);
+    @include nav_heading(1.1em, 500);
   }
   h3 {
-    @include nav_heading(1.25rem);
+    @include nav_heading(1em);
   }
 }
 
@@ -382,7 +382,7 @@ pre code {
   padding: $gutter 0;
 }
 
-.section-name {
+.section-name, .subsection-name {
   color: #666;
   display: block;
 }
@@ -415,7 +415,7 @@ pre code {
   margin-top: 15px;
 }
 
-.task-name-container {
+.task-name-container, .subsection-name-container {
   a[name] {
     &:before {
       content: "";
diff --git a/lib/jazzy/themes/fullwidth/templates/doc.mustache b/lib/jazzy/themes/fullwidth/templates/doc.mustache
index b5d56106e..6af90fbaf 100644
--- a/lib/jazzy/themes/fullwidth/templates/doc.mustache
+++ b/lib/jazzy/themes/fullwidth/templates/doc.mustache
@@ -49,7 +49,7 @@
         </section>
 
         {{> tasks}}
-        
+
       </article>
     </div>
     {{> footer}}
diff --git a/lib/jazzy/themes/fullwidth/templates/subsection.mustache b/lib/jazzy/themes/fullwidth/templates/subsection.mustache
index ea93963be..61441a492 100644
--- a/lib/jazzy/themes/fullwidth/templates/subsection.mustache
+++ b/lib/jazzy/themes/fullwidth/templates/subsection.mustache
@@ -1,10 +1,10 @@
-<div class="task-group">
-  <div class="task-name-container">
+<div class="subsection-group">
+  <div class="subsection-name-container">
     <a name="/{{uid}}"></a>
     <a name="//apple_ref/{{language_stub}}/Section/{{name}}" class="dashAnchor"></a>
     <span>
       <a class="token" href="#/{{uid}}">
-        <h3 class="section-name">{{name}}</h3>
+        <h3 class="subsection-name">{{name}}</h3>
       </a>
     </span>
   </div>

From baf598934e5cbb3471711d158d35870511eabd1b Mon Sep 17 00:00:00 2001
From: Leonardo Galli <leonardo.galli@bluewin.ch>
Date: Thu, 12 Jul 2018 22:52:33 +0200
Subject: [PATCH 06/13] Forgot one instance of Type.overview.

---
 lib/jazzy/sourcekitten.rb | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lib/jazzy/sourcekitten.rb b/lib/jazzy/sourcekitten.rb
index 419bdb3f9..7eaabb4da 100644
--- a/lib/jazzy/sourcekitten.rb
+++ b/lib/jazzy/sourcekitten.rb
@@ -117,7 +117,7 @@ def self.subdir_for_doc(doc)
         # File program elements under top ancestor’s type (Struct, Class, etc.)
         [top_level_decl.type.plural_url_name] +
           doc.namespace_ancestors.map(&:name)
-      elsif doc.type == SourceDeclaration::Type.overview
+      elsif doc.type.overview?
         # Categories live in their own directory
         # But subcategories live in a directory named after their parent
         doc.documentation_ancestors.map(&:name)

From ab9b537adecdda5fd7f91df420ecb16a0cfab351 Mon Sep 17 00:00:00 2001
From: Leonardo Galli <leonardo.galli@bluewin.ch>
Date: Sat, 14 Jul 2018 15:14:39 +0200
Subject: [PATCH 07/13] Moved level to a computed property.

---
 lib/jazzy/source_category.rb | 17 ++++++++++-------
 1 file changed, 10 insertions(+), 7 deletions(-)

diff --git a/lib/jazzy/source_category.rb b/lib/jazzy/source_category.rb
index 0d9bb6a87..598b3da90 100644
--- a/lib/jazzy/source_category.rb
+++ b/lib/jazzy/source_category.rb
@@ -8,7 +8,7 @@ module Jazzy
   class SourceCategory < SourceDeclaration
     extend Config::Mixin
 
-    def initialize(group, name, abstract, url_name, level = 1)
+    def initialize(group, name, abstract, url_name)
       super()
       self.type     = SourceDeclaration::Type.overview
       self.name     = name
@@ -16,7 +16,6 @@ def initialize(group, name, abstract, url_name, level = 1)
       self.abstract = Markdown.render(abstract)
       self.children = group
       self.parameters = []
-      self.level      = level
     end
 
     # Group root-level docs into custom categories or by type
@@ -29,12 +28,12 @@ def self.group_docs(docs)
       custom_categories + type_categories + uncategorized
     end
 
-    def self.group_custom_categories(docs, categories, level = 1)
+    def self.group_custom_categories(docs, categories)
       group = categories.map do |category|
         children = category['children'].flat_map do |child|
           if child.is_a?(Hash)
             # Nested category, recurse
-            children, docs = group_custom_categories(docs, [child], level + 1)
+            children, docs = group_custom_categories(docs, [child])
           else
             # Doc name, find it
             children, docs = docs.partition { |doc| doc.name == child }
@@ -49,7 +48,7 @@ def self.group_custom_categories(docs, categories, level = 1)
         end
         # Category config overrides alphabetization
         children.each.with_index { |child, i| child.nav_order = i }
-        make_group(children, category['name'], '', nil, level)
+        make_group(children, category['name'], '')
       end
       [group.compact, docs]
     end
@@ -67,11 +66,15 @@ def self.group_type_categories(docs, type_category_prefix)
       [group.compact, docs]
     end
 
-    def self.make_group(group, name, abstract, url_name = nil, level = 1)
+    def self.make_group(group, name, abstract, url_name = nil)
       group.reject! { |doc| doc.name.empty? }
       unless group.empty?
-        SourceCategory.new(group, name, abstract, url_name, level)
+        SourceCategory.new(group, name, abstract, url_name)
       end
     end
+
+    def level
+      return self.documentation_path.length
+    end
   end
 end

From 6cbe723466c99558571b8c491fcf1e6aa68e4e32 Mon Sep 17 00:00:00 2001
From: Leonardo Galli <leonardo.galli@bluewin.ch>
Date: Sat, 14 Jul 2018 15:19:42 +0200
Subject: [PATCH 08/13] Changed styles to be like the original categories.

---
 lib/jazzy/themes/fullwidth/assets/css/jazzy.css.scss | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/lib/jazzy/themes/fullwidth/assets/css/jazzy.css.scss b/lib/jazzy/themes/fullwidth/assets/css/jazzy.css.scss
index eab098db9..b8f7f7ef1 100644
--- a/lib/jazzy/themes/fullwidth/assets/css/jazzy.css.scss
+++ b/lib/jazzy/themes/fullwidth/assets/css/jazzy.css.scss
@@ -338,7 +338,7 @@ pre code {
   color: $navigation_task_color;
 }
 
-@mixin nav_heading($font-size: 1.5rem, $font-weight: 400, $margin: 1.0rem 0px 0px 0px) {
+@mixin nav_heading($font-size: 16px, $font-weight: 400, $margin: 12px 0px 0px 0px) {
   font-size: $font-size;
   font-weight: $font-weight;
   margin: $margin;
@@ -346,13 +346,13 @@ pre code {
 
 .nav-groups {
   h1 {
-    @include nav_heading(1.15em, 600);
+    @include nav_heading(16px, 400, 0px);
   }
   h2 {
-    @include nav_heading(1.1em, 500);
+    @include nav_heading();
   }
   h3 {
-    @include nav_heading(1em);
+    @include nav_heading();
   }
 }
 

From 7c400eb67d5dce9d1b1138121181c93be9399685 Mon Sep 17 00:00:00 2001
From: Leonardo Galli <leonardo.galli@bluewin.ch>
Date: Sun, 22 Jul 2018 14:52:19 +0200
Subject: [PATCH 09/13] Updated Readme to include info about custom categories.

---
 README.md | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/README.md b/README.md
index ebbf2f58a..639df30fe 100644
--- a/README.md
+++ b/README.md
@@ -222,6 +222,40 @@ Note that the `--include` option is applied before the `--exclude` option. For e
 Declarations with a documentation comment containing `:nodoc:` are excluded from the
 documentation.
 
+### Custom Categories
+
+By default, jazzy categorizes everything according to their types.
+
+Using `custom_categories` inside a jazzy config file, you can specify how symbols are
+categorized. This is really useful for larger projects, to keep a clean navigation area.
+
+A custom category is defined by a dictionary (or hash) containing the following keys:
+* `name` (string): The name of the category as it will be displayed.
+* `children` (array): The names of the symbols to include in this category.
+  Additionally, the array can also contain another dictionary
+  specifying a custom category. This allows for infinite subcategories.
+
+The `custom_categories` config file option accepts an array of
+custom category dictionaries and an example looks like this:
+
+```yaml
+custom_categories:
+  - name: My awesome Category
+    children:
+      - MyClass
+      - MyEnum
+      - name: My awesome Subcategory
+        children:
+          - MyStruct
+  - name: My other Category
+    children:
+      - MyGlobalFunction(_:)
+```
+
+A more concrete example can be found under [Siesta Nested Categories Example](https://git.io/fNvGB).
+
+**Note:** Currently the builtin themes only support up to three levels of nesting with the css. However, that can easily be adjusted.
+
 ## Troubleshooting
 
 #### Swift

From e263604bac5ec4790f913197f855e3491699f009 Mon Sep 17 00:00:00 2001
From: Leonardo Galli <leonardo.galli@bluewin.ch>
Date: Sun, 22 Jul 2018 14:56:05 +0200
Subject: [PATCH 10/13] Updated Changelog

---
 CHANGELOG.md | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6d99ebf83..dd2d4d858 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,7 +6,10 @@
 
 ##### Enhancements
 
-* None.
+* Add the ability to specify nested categories and create recursive
+  navigation for all templates.
+  [Leonardo Galli](https://github.com/galli-leo)
+  [#624](https://github.com/realm/jazzy/issues/624)
 
 ##### Bug Fixes
 

From 4c6c76c5955684f478981a7565fc961438ab83aa Mon Sep 17 00:00:00 2001
From: Leonardo Galli <leonardo.galli@bluewin.ch>
Date: Sun, 22 Jul 2018 14:56:44 +0200
Subject: [PATCH 11/13] Make rubocop happy again.

---
 lib/jazzy/source_category.rb | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lib/jazzy/source_category.rb b/lib/jazzy/source_category.rb
index 598b3da90..a974858e6 100644
--- a/lib/jazzy/source_category.rb
+++ b/lib/jazzy/source_category.rb
@@ -74,7 +74,7 @@ def self.make_group(group, name, abstract, url_name = nil)
     end
 
     def level
-      return self.documentation_path.length
+      documentation_path.length
     end
   end
 end

From bee9a9d4c407eb5d5d165acdc46813d02628c24c Mon Sep 17 00:00:00 2001
From: Leonardo Galli <leonardo.galli@bluewin.ch>
Date: Mon, 23 Jul 2018 23:12:58 +0200
Subject: [PATCH 12/13] Remove unecessary level accessor

---
 lib/jazzy/source_declaration.rb | 1 -
 1 file changed, 1 deletion(-)

diff --git a/lib/jazzy/source_declaration.rb b/lib/jazzy/source_declaration.rb
index 079dc3ddd..f9590cad3 100644
--- a/lib/jazzy/source_declaration.rb
+++ b/lib/jazzy/source_declaration.rb
@@ -112,7 +112,6 @@ def display_other_language_declaration
     attr_accessor :end_line
     attr_accessor :nav_order
     attr_accessor :url_name
-    attr_accessor :level
 
     def alternative_abstract
       if file = alternative_abstract_file

From 75e4721651fcfe45d25d1b343446ffa3d8b35fe1 Mon Sep 17 00:00:00 2001
From: Leonardo Galli <leonardo.galli@bluewin.ch>
Date: Mon, 23 Jul 2018 23:16:51 +0200
Subject: [PATCH 13/13] Fixed Changelog

---
 CHANGELOG.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index dd2d4d858..113419298 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,8 +6,8 @@
 
 ##### Enhancements
 
-* Add the ability to specify nested categories and create recursive
-  navigation for all templates.
+* Add the ability to specify nested categories and create recursive navigation
+  for all templates.  
   [Leonardo Galli](https://github.com/galli-leo)
   [#624](https://github.com/realm/jazzy/issues/624)