Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 3 commits into from
Dec 23, 2023
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
47 changes: 47 additions & 0 deletions docs/examples/in-page-toc.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
: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.

We **do not recommend** using this directive on pages that use this theme
gabalafou marked this conversation as resolved.
Show resolved Hide resolved
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 (directions below).
gabalafou marked this conversation as resolved.
Show resolved Hide resolved

.. contents:: Page contents
:local:


Local contents directive
------------------------

What is a local contents directive?

.. code-block:: rst

.. contents:: Page contents
:local:

You add this directive near the top of your ``.rst`` page to insert a table of
contents for that page, which is what this page does.

gabalafou marked this conversation as resolved.
Show resolved Hide resolved

Turn off right sidebar for a single page
----------------------------------------
gabalafou marked this conversation as resolved.
Show resolved Hide resolved

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.
1 change: 1 addition & 0 deletions docs/examples/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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/>
Expand Down
4 changes: 0 additions & 4 deletions docs/user_guide/theme-elements.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down