From 32092a2f3eda17ad075f13994418f679efff9005 Mon Sep 17 00:00:00 2001
From: Chris Holdgraf <choldgraf@berkeley.edu>
Date: Mon, 8 Jun 2020 17:10:10 -0700
Subject: [PATCH] adding support for multiple top-level headers

---
 docs/demo/index.rst               |  1 +
 docs/demo/mult_headers.rst        | 57 +++++++++++++++++++++++++++++++
 pydata_sphinx_theme/__init__.py   |  7 +++-
 pydata_sphinx_theme/docs-toc.html |  6 ++--
 4 files changed, 67 insertions(+), 4 deletions(-)
 create mode 100644 docs/demo/mult_headers.rst

diff --git a/docs/demo/index.rst b/docs/demo/index.rst
index 71de1e4e9..bf106152f 100644
--- a/docs/demo/index.rst
+++ b/docs/demo/index.rst
@@ -16,6 +16,7 @@ the left sidebar to see how various elements look on this theme.
     lists_tables
     markdown
     example_pandas
+    mult_headers
 
 .. toctree::
     :maxdepth: 3
diff --git a/docs/demo/mult_headers.rst b/docs/demo/mult_headers.rst
new file mode 100644
index 000000000..7395541f4
--- /dev/null
+++ b/docs/demo/mult_headers.rst
@@ -0,0 +1,57 @@
+Top-level headers and the TOC
+=============================
+
+Your right table of contents will behave slightly differently depending on
+whether your page has one top-level header, or multiple top-level headers. See
+below for more information.
+
+An example with multiple top-level headers
+==========================================
+
+If a page has multiple top-level headers on it, then the in-page Table of Contents
+will show each top-level header.
+**On this page, there are multiple top-level headers**. As a result, the top-level
+headers all appear in the right Table of Contents. Here's an example of a page structure
+with multiple top-level headers:
+
+
+.. code-block:: rst
+
+   My first header
+   ===============
+
+   My sub-header
+   -------------
+
+   My second header
+   ================
+
+   My second sub-header
+   --------------------
+
+And here's a second-level header
+--------------------------------
+
+Notice how it is nested *underneath* "Top-level header 2" in the TOC.
+
+
+An example with a single top-level header
+=========================================
+
+If the page only has a single top-level header, it
+is assumed to be the page title, and only the headers **underneath** the top-level
+header will be used for the right Table of Contents.
+
+On most pages in this documentation, only a single top-level header is used. For
+example, they have a page structure like:
+
+.. code-block:: rst
+
+   My title
+   ========
+
+   My header
+   ---------
+
+   My second header
+   ----------------
diff --git a/pydata_sphinx_theme/__init__.py b/pydata_sphinx_theme/__init__.py
index aa020baeb..5128fadf7 100644
--- a/pydata_sphinx_theme/__init__.py
+++ b/pydata_sphinx_theme/__init__.py
@@ -65,7 +65,12 @@ def get_page_toc_object():
         self_toc = TocTree(app.env).get_toc_for(pagename, app.builder)
 
         try:
-            nav = docutils_node_to_jinja(self_toc.children[0])
+            # If there's only one child, assume we have a single "title" as top header
+            # so start the TOC at the first item's children (AKA, level 2 headers)
+            if len(self_toc.children) == 1:
+                nav = docutils_node_to_jinja(self_toc.children[0]).get("children", [])
+            else:
+                nav = [docutils_node_to_jinja(item) for item in self_toc.children]
             return nav
         except Exception:
             return {}
diff --git a/pydata_sphinx_theme/docs-toc.html b/pydata_sphinx_theme/docs-toc.html
index 755db42eb..4a6085dab 100644
--- a/pydata_sphinx_theme/docs-toc.html
+++ b/pydata_sphinx_theme/docs-toc.html
@@ -1,6 +1,6 @@
 {% set page_toc = get_page_toc_object() %}
 
-{%- if page_toc.children | length >= 1 %}
+{%- if page_toc | length >= 1 %}
 <div class="tocsection onthispage pt-5 pb-3">
     <i class="fas fa-list"></i> On this page
 </div>
@@ -8,7 +8,7 @@
 
 <nav id="bd-toc-nav">
     <ul class="nav section-nav flex-column">
-    {% for item in page_toc.children recursive %}
+    {% for item in page_toc recursive %}
         <li class="nav-item toc-entry toc-h{{ loop.depth + 1 }}">
             <a href="{{ item.url }}" class="nav-link">{{ item.title }}</a>
         {%- if item.children -%}
@@ -21,4 +21,4 @@
     </ul>
 </nav>
 
-{% include "edit_this_page.html" %}
\ No newline at end of file
+{% include "edit_this_page.html" %}