Layout and Page Elements

Control page structure, navigation, and content layout.

Sidebars

There are two kinds of sidebar-like content in quantecon-book-theme: standard {sidebar} directives and a theme-specific {margin} directive.

Tip

Sidebar content will generally overlap with the right-hand TOC space. When sidebar content scrolls into view, the TOC hides automatically.

Margins

Content that pops out to the right margin at wide viewports (≥1200px):

```{margin} **My margin title**
Here is my margin content, it is pretty cool!
```

Margin example

In the quantecon-book-theme, this pops out to the right margin:

Here is my margin content — It is pretty cool!

Content sidebars

In-line sidebars that allow page text to flow around them:

```{sidebar} **My sidebar title**
Here is my sidebar content, it is pretty cool!
```

Note how the content wraps around the sidebar. Some elements (notes, code cells) may clash with sidebars — try {margin} instead if this happens.

My sidebar title

Note

Here is my sidebar content, it is pretty cool!

Content in margins and sidebars

Sidebar/margin content supports code blocks:

Margin example — Code blocks

In the theme, this renders as a code block in the right margin:

print("here is some python")

````{margin} Code blocks in margins
```python
print("here is some python")
```
````

As well as admonitions and images:

Margin example — Notes

In the theme, this renders as a note in the right margin:

Note

Wow, a note with an image in a margin!

````{margin} **Notes in margins**
```{note}
Wow, a note with an image in a margin!
![](../images/cool.jpg)
```
````

Margin figure captions

A figure with a caption to the right:

Fig. 1 And here is my figure caption

Reference with And here is my figure caption or Fig. 1.

A figure with caption below, placed in the margin:

Fig. 2 And here is my figure caption

Reference with And here is my figure caption or Fig. 2.

Full-Width Content

Extend content into the right margin by adding the full-width class:

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

Note

This content will be full-width

Tip

A note for ipynb users If you are using a Jupyter Notebook as inputs to your documentation using the MyST-NB extension, you can trigger this behavior with a code cell by adding a full-width tag to the cell.

Quotations and Epigraphs

A standard quote:

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.

An epigraph draws more attention:

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.

With 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.

—Jo the Jovyan, the jupyter book docs

Controlling the Left Navigation Bar

Expand sections

Keep sub-sections permanently expanded:

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

Add a header to the TOC

Use :caption: My header text in your toctree directive.

Show the home page in the TOC

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