From 70960a8371c0a18f03ffdf48def000bc5a29215e Mon Sep 17 00:00:00 2001
From: Nikhil Benesch <nikhil.benesch@gmail.com>
Date: Sun, 2 Jul 2017 12:31:19 -0400
Subject: [PATCH 1/2] properly render default collapsed header when no matching
 sidebar entry

Pages which do not have a sidebar entry should render "Docs Menu" in the
header, like the used to.
---
 _includes/sidebar.html | 13 ++++++-------
 1 file changed, 6 insertions(+), 7 deletions(-)

diff --git a/_includes/sidebar.html b/_includes/sidebar.html
index 5af5781153a..6c85013de21 100755
--- a/_includes/sidebar.html
+++ b/_includes/sidebar.html
@@ -53,12 +53,9 @@
             });
         </script>
 
-        <ul id="mysidebar" class="nav {% if page.url == '/' or page.url == '/search.html' %}nav--home{% endif %}" style="display: none">
+        <ul id="mysidebar" class="nav {% if page.name == 'index.md' or page.url == '/search.html' %}nav--home{% endif %}" style="display: none">
             <div class="sidenav-arrow"><img src="{{ 'images/sidenav-arrow.svg' | relative_url }}" alt="Sidenav arrow"></div>
-            <div class="collapsed-header">
-              <div id="ch-breadcrumbs" class="collapsed-header__pre"></div>
-              <div id="ch-title"></div>
-            </div>
+            <div class="collapsed-header">Docs Menu</div>
             <li class="search-wrap">
                 <div class="search">
                     <span class="fa fa-search"></span>
@@ -103,9 +100,11 @@
                       });
                       var active = (urls.indexOf(location.pathname) !== -1);
                       if (active) {
-                        $("#ch-breadcrumbs")
+                        var breadcrumbs = $("<div>")
+                          .addClass("collapsed-header__pre")
                           .html(paths.join("<div class=\"arrow-down arrow-down--pre\"></div>\n"));
-                        $("#ch-title").html(item.title);
+                        var title = $("<div>").html(item.title);
+                        $(".collapsed-header").empty().append(breadcrumbs, title);
                       }
                       var subitems = renderItems(item.items, paths.concat(item.title));
                       var a = $("<a>")

From cac028b050bbe2656035226b35a9b6d8eb8925eb Mon Sep 17 00:00:00 2001
From: Nikhil Benesch <nikhil.benesch@gmail.com>
Date: Tue, 4 Jul 2017 13:46:45 -0400
Subject: [PATCH 2/2] document the sidebar rendering code

Addresses review feedback from #1652.
---
 _includes/sidebar.html | 34 +++++++++++++++++++++++++++++++++-
 1 file changed, 33 insertions(+), 1 deletion(-)

diff --git a/_includes/sidebar.html b/_includes/sidebar.html
index 6c85013de21..aa0f83f6026 100755
--- a/_includes/sidebar.html
+++ b/_includes/sidebar.html
@@ -55,7 +55,19 @@
 
         <ul id="mysidebar" class="nav {% if page.name == 'index.md' or page.url == '/search.html' %}nav--home{% endif %}" style="display: none">
             <div class="sidenav-arrow"><img src="{{ 'images/sidenav-arrow.svg' | relative_url }}" alt="Sidenav arrow"></div>
-            <div class="collapsed-header">Docs Menu</div>
+            <div class="collapsed-header">
+              Docs Menu
+              {% comment %}
+                On pages that match a sidebar entry, the JavaScript below
+                injects the following HTML.
+                <div class="collapsed-header__pre">
+                  Breadcrumb level 1
+                  <div class=\"arrow-down arrow-down--pre\"></div>
+                  Breadcrumb level 2
+                </div>
+                <div>Page title</div>
+              {% endcomment %}
+            </div>
             <li class="search-wrap">
                 <div class="search">
                     <span class="fa fa-search"></span>
@@ -90,6 +102,23 @@
                     return "stable";
                   })();
 
+                  // Given a sidebar hierarchy (see _data/sidebar-data-v1.0.json
+                  // for an example), returns a jQuery <ul> element with the
+                  // following structure:
+                  //
+                  // <ul>
+                  //   <li class="tier-1">
+                  //    <a href="{{ item.url }}">{{ item.title }}</a>
+                  //     <ul>
+                  //       {% for item in item.items %}
+                  //         <li class="tier-2">...</li>
+                  //       {% endfor %}
+                  //     </ul>
+                  //   </li>
+                  // </ul>
+                  //
+                  // Additionally injects breadcrumbs for the active sidebar
+                  // entry, if any, into the `.collapsed-header` element above.
                   function renderItems(items, paths) {
                     if (!items || items.length == 0)
                         return $();
@@ -100,6 +129,9 @@
                       });
                       var active = (urls.indexOf(location.pathname) !== -1);
                       if (active) {
+                        // This mutation inside an otherwise pure function is
+                        // unfortunate, but doing it here avoids a separate
+                        // traversal of the sidebar data.
                         var breadcrumbs = $("<div>")
                           .addClass("collapsed-header__pre")
                           .html(paths.join("<div class=\"arrow-down arrow-down--pre\"></div>\n"));