Configuration and page elements

There are a number of ways to configure sphinx-book-theme. This page covers some of the main ways to do so. It also serves as a reference to make sure that visual elements look correct

Full-width content

Full-width content extends into the right margin, making it stand out against the rest of your book’s content. To add full-width content to your page, add the class full-width to any of the elements in your documentation. For example, you can add a full-width tag to a note element like this:

```{note}
:class: full-width
This content will be full-width
```

This code results in the following output:

Note

This content will be full-width

Quotations and epigraphs

Here is what quotations and epigraphs look like in sphinx-book-theme:

A quote with no attribution:

Here’s my quote, it’s pretty neat. I wonder how many lines I can create with a single stream-of-consciousness quote. I could try to add a list of ideas to talk about. I suppose I could just keep going on forever, but I’ll stop here.

Sometimes you’d like to draw more attention to a quote. To do so, use the {epigraph} directive. Below is an epigraph, click the button to the right of it to show the code that was used to generate it:

Here’s my quote, it’s pretty neat. I wonder how many lines I can create with a single stream-of-consciousness quote. I could try to add a list of ideas to talk about. I suppose I could just keep going on forever, but I’ll stop here.

```{epigraph}
Here's my quote, it's pretty neat.
I wonder how many lines I can create with
a single stream-of-consciousness quote.
I could try to add a list of ideas to talk about.
I suppose I could just keep going on forever,
but I'll stop here.
```

You can also add an attribution to epigraphs by adding a blank line, followed by a line that starts with --. This will be renderered like so:

Here’s my quote, it’s pretty neat. I wonder how many lines I can create with a single stream-of-consciousness quote. I could try to add a list of ideas to talk about. I suppose I could just keep going on forever, but I’ll stop here.

—Jo the Jovyan, the jupyter book docs

```{epigraph}
Here's my quote, it's pretty neat.
I wonder how many lines I can create with
a single stream-of-consciousness quote.
I could try to add a list of ideas to talk about.
I suppose I could just keep going on forever,
but I'll stop here.

-- Jo the Jovyan
```

Controlling the left nav bar

You can control some elements of the navigation bar. Here are the main features:

Expand sections of your navbar

You can keep certain sub-sections of pages to be permanently expanded in your left Table of Contents. To do so, add a list of any pages you wish to be expanded in the following configuration:

html_theme_options = {
    ...
    "expand_sections": ["list", "of", "pages"]
    ...
}

Each page that is in expand_sections will be expanded in your left TOC.

Add a header to your TOC

If you’d like to add a header above a section of TOC links, use :caption: My header text in your toctree directive for that section.

Adding the home page to your TOC

If you’d like to have the home page listed in your TOC links, use the following configuration in conf.py:

html_theme_options = {
    ...
    "home_page_in_toc": True
    ...
}

Numbering your TOC sections

If you’d like to number your Table of Contents sections, use the following configuration in conf.py:

html_theme_options = {
    ...
    "number_toc_sections": True
    ...
}

Note: external links will be skipped in numbering.

Add metadata open graph tags to your site

OpenGraph tags can be used to generate previews and descriptions of your website. These will be automatically generated based on your page’s content and title. However, generating them requires knowing the full URL of your website ahead of time.

To enable metadata tags for your documentation, use the following configuration in conf.py:

html_baseurl = "https://<your-site-baseurl>"

For example, the value of this field for this documentation is:

html_baseurl = "https://sphinx-book-theme.readthedocs.io/en/latest/"