Jupyter-book: Jupyter Book - Where is the theme defined / customized

[lwasser]

Hi there @choldgraf ! As you know i've been thinking a lot about using JupyterBook for our textbooks on earthdatascience.org . I'd like to better understand where the theme files are in the book and how i could begin to modify them to skin the book to match our site.

SEO is important to use so we want multiple books in one place with a similar header / navigation top bar. And i have some ideas on surfacing content pages within the book as well for better seo!! But... to begin, how does the sphinx theme integrate into the book and where would i go to begin to skin a book?

iframes and embeds are not ideal because they are not as SEO friendly.

Many thanks for any suggestions!

[choldgraf]

hey! so, the theme is defined here: https://github.com/executablebooks/sphinx-book-theme

jupyterbook is just using that theme straight-up

if you'd like to add your own CSS, you can do so by following these instructions:

https://jupyterbook.org/advanced/sphinx.html#custom-css-or-javascript

However, that will just let you over-ride the CSS or javascript. You might be able to alter the pages to add a top-bar, but another way that you could try to do this is by creating your own theme that is a fork of the sphinx-book-theme, and then activating it with these manual sphinx over-ride instructions: https://jupyterbook.org/advanced/sphinx.html#manual-sphinx-configuration

maybe that could be a start?

[lwasser]

thank you @choldgraf this is super helpful. i should have thought to look for a theme in this organization!

so in that override

sphinx:
  config:
    key1: value1

do you have an example of how i'd go about specifying a custom theme. all i really want to customize right now involves adding a top bar with navigation and a logo. you have nice typography on the site so i wont do much with the styles.

would that look something like

sphinx:
  config:
    html_theme = "sphinx_rtd_theme"

And if the above is correct or on the right path, how would sphinx know to look for a theme in a repo somewhere?

i think the page i want to manipulate is this template

https://github.com/executablebooks/sphinx-book-theme/blob/master/sphinx_book_theme/layout.html

and potentially right here -- https://github.com/executablebooks/sphinx-book-theme/blob/master/sphinx_book_theme/layout.html#L38
i'd add a div and some navigation stuff to send users back to earth data science.

this all looks very liquid like and familiar which is nice :)
thank you again.

[choldgraf]

indeed that all sounds correct to me!

and the template engine is called "Jinja", which is very similar to liquid in many ways (actually, I like it better because you can write functions in Python that you can then call from the template)

just a note that some of this is diving into "advanced sphinx" territory :-)

[firasm]

Hi @lwasser - were you able to accomplish what you were trying to do ? I think I'm trying to do something similar and add a navigation bar to the home page.

Here is a visual example of what I'm trying to do:

Essentially a styled "home page" for my Jupyterbook that contains the course syllabus (similar to this):

with some sort of navigation to link to the actual "book" part of the site (existing side-bar is fine).

If you notice, the examples above requires two separate sites that point to each other - NOT ideal! The home page was done with Hugo and the bookdown package was used for the actual class notes. I could actually accomplish the same thing with a Hugo site linked to a Jupyterbook, but it seems overkill _just_ to get one styled html page. Also it's nice (workflow wise) to have one build system controlling all content on a site.

If someone has an example of styling just a single page, I'd love to see it - I'm sure I could hack something together with an example.

Thanks for a great product!

[choldgraf]

just a note that I believe jupyter books are self-contained HTML, which means that you could put a jupyter-book in a _sub-directory_ of another site (e.g. a jekyll site or a hugo site). Then at least the URLs would be the same even if the layout of the page was different.

[firasm]

That is a great point! I didn't think of that - thanks! I think I'll do that.

[lwasser]

ahh yes... i'm still interested in this. What i want is to add a top navigation bar. given in our case we have a lot of different types of content... it would be ideal to be able to add a header bar with a set of links back to our other courses and textbooks and site elements. it's a simple add but i'm realizing i may need to dig into sphinx a bit to get there.

when a user can't get back to the main site you often lose them.

[choldgraf]

would it be enough for me to allow you to add something like a {{ header_html }} that is configurable, and would go before any of the other content on the page? Then you could manually add HTML that would show up on the built page if you wanted something like a top-bar header. Though I fear it wouldn't be the most seamless and user-friendly experience since you'd be hard-coding HTML that would be the same on every page...

[choldgraf]

I'm gonna close this one since it's not clear to me what's the actionable path forward, but if we need to resolve something else let's open another issue!

[lwasser]

hi @choldgraf don't hate me for being so slow to followup BUT if there were a {{header_html}} element it would actually resolve the issues that i have currently. i could add a top bar navigation and menu which is all that i need to add. the one question would be - could we also still add a javascript call above the <body> tag and potentially custom css? if that combination is possible that would be a perfect solution for us.

[choldgraf]

@lwasser could you open that up as an issue in the sphinx-book-theme repository? That way the title could be a bit more actionable and tied to your specific concern?

[lwasser]

absolutely @choldgraf !