Get started#
This is a short step-by-step tutorial to get started with the Sphinx Book Theme.
Note
This documentation and the examples below are written with MyST Markdown, a form of markdown that works with Sphinx. For more information about MyST markdown, and to use MyST markdown with your Sphinx website, see the MyST-parser documentation
Prerequisites#
You should be relatively familiar with the Sphinx ecosystem, and have it installed locally on your computer.
Note
If you don’t already have a Sphinx site ready to customize, you can create one with:
sphinx-quickstart
Install and activate the theme#
First install sphinx-book-theme
with pip
:
pip install sphinx-book-theme
then, activate the theme in your Sphinx configuration (conf.py
):
...
html_theme = "sphinx_book_theme"
...
This will activate the Sphinx Book Theme for your documentation.
Note
You may need to comment-out your html_theme_options
configuration depending on your previous theme.
Add some margin content to a page#
There are a few special kinds of content that this theme supports, largely inspired by the Tufte CSS theme styles. One kind of content is margin content. This allows you to “pop out” content to the side of the page, in the margins. Add some margin content to a page by adding the following directive (written with MyST Markdown).
```{margin} Look, some margin content!
On wider screens, this content will pop out to the side!
```
On wide screens, margin content will pop out to the side of the page and allow content underneath it to move upwards. This allows you to provide extra information without interrupting the flow of information.
There are many other things that you can do with the Sphinx Book Theme. Now that you’ve gotten a start, check out the other sections to the left to learn more about how to use it.