Fix landmark-unique error due to in-page TOC (#1607)

* landmark unique error due to in-page TOC * Apply suggestions from code review Co-authored-by: Tania Allard <[email protected]> * fix lint? --------- Co-authored-by: Tania Allard <[email protected]>
pydata · Dec 23, 2023 · 5b417ad · 5b417ad
1 parent 3de3059
commit 5b417ad
Show file tree

Hide file tree

Showing 3 changed files with 50 additions and 4 deletions.
diff --git a/docs/examples/in-page-toc.rst b/docs/examples/in-page-toc.rst
@@ -0,0 +1,49 @@
+:html_theme.sidebar_secondary.remove: true
+
+Test of in-page TOC with no right sidebar
+=========================================
+
+This page tests that the local contents directive looks okay.
+
+.. attention::
+
+    We **do not recommend** using this directive on pages that use this theme
+    because PyData Theme provides an in-page table of contents in the right sidebar
+    by default.
+
+If you do choose to use an inline, in-page table of contents, we recommend that
+you turn off the right sidebar as follows.
+
+.. contents:: Page contents
+    :local:
+
+
+Add a local table of contents (in-page)
+---------------------------------------
+
+Add the local table of contents directive near the top of your ``.rst`` page:
+
+.. code-block:: rst
+
+    .. contents:: Page contents
+        :local:
+
+This directive will generate a table of contents for the section where this was
+added, as shown on this page.
+
+
+Turn off the right sidebar for a single page
+--------------------------------------------
+
+On the very top line of your ``.rst`` file, insert the following line:
+
+.. code-block:: rst
+
+    :html_theme.sidebar_secondary.remove: true
+
+This will render the page without the right sidebar, also known as the secondary
+sidebar, which contains the table of contents for that page.
+
+Be aware that if you remove the sidebar you may also remove the "Edit on ..."
+and "Show source" links for that page, since by default those are configured for
+the right sidebar.
diff --git a/docs/examples/index.rst b/docs/examples/index.rst
@@ -29,6 +29,7 @@ See the sections in the primary sidebar and below to explore.
 
     no-sidebar
     persistent-search-field
+    in-page-toc
     subpages/index
     mult_headers
     Link to an external site <https://jupyterbook.org/>

diff --git a/docs/user_guide/theme-elements.md b/docs/user_guide/theme-elements.md
@@ -3,10 +3,6 @@
 There are a few elements that are unique or particularly important to this theme.
 Some of these are triggered with configuration or Markdown syntax that is unique to the theme, and we cover them below.
 
-```{contents} Page contents
-:local:
-```
-
 ## Mathematics
 
 Most Sphinx sites support math, but it is particularly important for scientific computing, so we illustrate support here as well.