Customizing the Theme

[anindya-saha]

Hi Team,
I understood that Jupyter Book uses the https://github.com/executablebooks/sphinx-book-theme by default. I would like to make some customization to the layout, footer, navbar etc in the sphinx-book-theme. I would like to customize the theme. How can I achieve that in Jupyter Book?

[choldgraf]

I'd recommend checking out this page for now: https://jupyterbook.org/advanced/sphinx.html#custom-css-or-javascript

[asahalyft]

Thanks. I already saw that. What I am looking for is customizing the theme, layouts, adding additional top bar menu items etc. which is not possible with just custom css and js.

[chrisjsewell]

I would note that there are already some open issues on sphinx-book-theme, to improve extensibility, like #182. You can follow that, or feel free to open an issue regarding a specific extensible feature you would like to see.

For advanced use, you can also extend/override the templates used by the theme:
https://www.sphinx-doc.org/en/master/templating.html#jinja-sphinx-templating-primer

[ria-rivera]

Hi @choldgraf, I noticed that the linked section is no longer in the published docs. Does this mean that using custom css is no longer supported?

[OriolAbril]

I think the content moved to https://jupyterbook.org/advanced/html.html#custom-css-or-javascript

[phaustin]

Not sure it's the correct approach, but you can fork sphinx-book-theme and make changes to the jinja2 templates (for example:
executablebooks/sphinx-book-theme@master...phaustin:localhost )

I found I also had to bump the version number and fork jupyter-book to change the pinning to force use of my modified theme -- so that my requirements.txt file looks like this:
https://github.com/phaustin/Problem-Solving-with-Python-37-Edition/blob/volume/user_notebook/requirements.txt

[choldgraf]

Yeah - if you wanna make more substantial changes you can always provide your own custom Sphinx configuration (also documented on that page) to modify the theme etc

[phaustin]

@choldgraf -- one thing that confused me when I was looking at whether I could just put a new html_theme in config.py was the hardwired import of sphinx_book_theme here:
https://github.com/executablebooks/jupyter-book/blob/master/jupyter_book/commands/__init__.py#L26
is that a bug or a feature? (this was after grepping the source led me to the config test, where html_theme is set to "other")
https://github.com/executablebooks/jupyter-book/blob/master/tests/test_config.py#L27)

[chrisjsewell]

Heya, I'm not sure by bug? This is only an install activated when showing package versions, and will never fail anyway, because jupyter-book is always installed with sphinx-book-theme as part of its required dependencies.
Of course, for advanced users, jupyter-book is essentially just an opinionated sphinx-build; so if you are looking to make widespread changes to it, you can always consider just using myst-nb directly.

[CodeCox]

@chrisjsewell

jupyter-book is essentially just an opinionated sphinx-build

What jupyter-book 'features' or 'improvements' would I lose by just using myst-nb directly with Sphinx?

[choldgraf]

mostly just the ability to use a _toc.yml file and the jupyter book _config.yml file, and some stuff will be slightly differently-configured in sphinx vs. jupyter book, but the broad functionality should all be quite similar. Mostly Jupyter Book makes those opinions relatively easy for people to quickly deploy, but it is not doing anything crazy that you couldn't also do with Sphinx (that is the whole point!)

[dolsysmith]

A question related to the above: I would like to include a custom Jinja template within the standard JupyterBook/sphinx-book-theme. This template is only applied to a handful of MD files, which function as supplemental/standalone content relative to the main book. My main reason for wanting to build them as part the JupyterBook build is to avoid a separate workflow (involving Jekyll or similar).

Per the Sphinx documentation, I put my custom template in a _templates subfolder within the folder for my book, and I added the following line to the Sphinx conf.py:

templates_path = ['_templates']

However, this method seems to have overwritten some other templates path, because I'm now getting the following error on build:

jinja2.exceptions.TemplateNotFound: toggle-primary-sidebar.html

I don't see a templates_path key in the default JupyterBook conf file, but I'm guessing it's defined somewhere else and is being overwritten by my own directory.

Any ideas as to how I can include a single custom template without forking the theme itself?

Thanks for your help!