Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jupyter Book - Where is the theme defined / customized #718

Closed
lwasser opened this issue Jun 16, 2020 · 12 comments
Closed

Jupyter Book - Where is the theme defined / customized #718

lwasser opened this issue Jun 16, 2020 · 12 comments
Labels
enhancement New feature or request

Comments

@lwasser
Copy link

lwasser commented Jun 16, 2020

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!

@lwasser lwasser added the enhancement New feature or request label Jun 16, 2020
@choldgraf
Copy link
Collaborator

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
Copy link
Author

lwasser commented Jun 16, 2020

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
Copy link
Collaborator

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
Copy link
Contributor

firasm commented Jul 6, 2020

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):

Screen Shot 2020-07-06 at 5 43 23 PM

with some sort of navigation to link to the actual "book" part of the site (existing side-bar is fine).
Screen Shot 2020-07-06 at 5 48 16 PM

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
Copy link
Collaborator

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
Copy link
Contributor

firasm commented Jul 9, 2020

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

@lwasser
Copy link
Author

lwasser commented Jul 13, 2020

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
Copy link
Collaborator

choldgraf commented Jul 13, 2020

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
Copy link
Collaborator

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
Copy link
Author

lwasser commented Aug 13, 2020

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
Copy link
Collaborator

@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
Copy link
Author

lwasser commented Aug 13, 2020

absolutely @choldgraf !

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request
Projects
None yet
Development

No branches or pull requests

3 participants