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.

Sign up for GitHub

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

Jump to bottom

Allow for header customization #182

Closed
lwasser opened this issue Aug 13, 2020 · 20 comments · Fixed by #677 · May be fixed by #559
Closed

Allow for header customization #182

lwasser opened this issue Aug 13, 2020 · 20 comments · Fixed by #677 · May be fixed by #559
Labels
enhancement New feature or request

Comments

@lwasser
Copy link

lwasser commented Aug 13, 2020

This related to a discussion here

Is your feature request related to a problem? Please describe.

I'd love to use jupyter book for my textbooks. i have 3 currently on our learning portal. the problem is that because we have multiple books and a portal that is SEO optimized, we want to maintain visual branding of all of our content. This means that ideally we'd like to have the ability to add a header to the book with links back to our main site and to customize the css /colors potentially to better match our existing theme. The site currently is being redesigned btw.

As i'm considering this a footer element would be nice to have too - at CU we have to acknowedge certain things in the footer.

Describe the solution you'd like

I'd like a simple way to adding a header with HTML to all book html pages.
This will likely mean we also need to be able to add stuff to the header (above the <body> tag in the <head> section - which might include css and also js.

Describe alternatives you've considered

i've considered creating our own theme but that seems like a lot of work to add a header and css to a page! i'd also have to learn a lot of new things to customize sphinx.

Additional context

have a look at our website and you will see on the home page links to three textbooks. in the site they retain the site skin. they are not separate websites.

thank you for considering this!
@lwasser lwasser added the enhancement New feature or request label Aug 13, 2020
@welcome
Copy link

welcome bot commented Aug 13, 2020

Thanks for opening your first issue here! Engagement like this is essential for open source projects! 🤗

If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.

If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).

Welcome to the EBP community! 🎉

@ghutchis
Copy link

Yes, please. If a header + w/ adaptable CSS, I'd adopt this in a heartbeat for several projects.

@chrisjsewell
Copy link
Member

Sounds reasonable 😄
On the case of adaptable CSS, maybe I'm missing something, but can you not just use https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_css_files to add your own CSS?
(this is also mentioned in https://jupyterbook.org/advanced/sphinx.html?highlight=css#custom-css-or-javascript)

@ghutchis
Copy link

I just found that part of the documentation - for me, that feature (loading additional CSS and JS) should be enough, although it's sometimes helpful to insert a <script> tag to a CDN, e.g.

<script src="https://cdnjs.cloudflare.com/ajax/libs/3Dmol/1.4.0/3Dmol-min.js"></script>

The biggest thing would be to add HTML for a header / masthead, similar to the extra_footer:

html:
    extra_header: |
     <div class="masthead__menu">
       ..
     </div>

@lwasser
Copy link
Author

lwasser commented Aug 13, 2020

@chrisjsewell it is very possible that i've forgotten about some of the docs associated with customization of the book! yes

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

the approach above would work for CSS and javascript... so i'm just back to wanting a header option!! sounds like @ghutchis is also in a similar situation! :) thank you for the positive feedback.

branding is so important to us.

@chrisjsewell chrisjsewell changed the title Customize sphinx theme with a header and (maybe) css? Allow for header customization Aug 13, 2020
@ghutchis
Copy link

ghutchis commented Aug 27, 2020 •
edited
Loading

Is there anything I can do to help on this? I have a case that I'd like to deploy soon and would be willing to write some code if I can get some pointers.

@pradyunsg
Copy link
Member

<script> tag to a CDN, e.g.

IIRC, you can "just" add https://cdnjs.cloudflare.com/ajax/libs/3Dmol/1.4.0/3Dmol-min.js as the path to the file, and Sphinx should do the right thing for it.

would be willing to write some code if I can get some pointers.

All the HTML for the top bar is in: https://github.com/executablebooks/sphinx-book-theme/blob/master/sphinx_book_theme/topbar.html

I think we could get away by merely adding a few "strategically placed" Jinja2 blocks in topbar.html, and that can serve as an extension point for someone that wants to customize it.

In case, you wanna fiddle around with the styling... Most of the relevant SCSS is here: https://github.com/executablebooks/sphinx-book-theme/blob/master/sphinx_book_theme/scss/sphinx-book-theme.scss#L570. Be warned: there's a lot of... uhm... not-so-straightforward-to-understand things happening with the layouting of the top bar. :)

@choldgraf
Copy link
Member

Yep - my guess is that the trickiest part of this will be making sure that the CSS behaves expectedly (because I believe right now we're hard-coding some rules that expect elements to be at the top of the viewport). Would love to see improvements to the CSS that do this more reasonably 👍

@ghutchis
Copy link

ghutchis commented Aug 29, 2020 •
edited
Loading

CSS may be beyond my ability, but I'll take a stab with some strategic Jinja2 and report back tomorrow.
(Last time I did strategic web coding was in the pre-CSS era.)

@AllenDowney
Copy link

I would also like to be able to add a custom header and/or footer to the pages generated by JupyterBook. Has anyone figured out a good way to do this, and would you be able to write up the steps? Thank you!

@ghutchis
Copy link

I ended up adapting the pydata-sphinx theme.

@AllenDowney
Copy link

@ghutchis Would you be able to provide a brief step-by-step?

@jackgerrits
Copy link

+1 to this, would really like to be able to use a custom header

@lwasser
Copy link
Author

lwasser commented Jun 22, 2021

@ghutchis i'd love to see your approach to doing this. @choldgraf had mentioned making a new theme that suits our needs but i'm not sure how that would get implemented when using jupyter book to build the book.

@choldgraf
Copy link
Member

The most straightforward way to play around with other themes with Jupyter Book is to use the custom Sphinx configuration as documented here:

https://jupyterbook.org/advanced/sphinx.html#manual-sphinx-configuration

Basically you'd use something like:

...
sphinx:
  config:
    html_theme: pydata_sphinx_theme

This might be a bit unpredictable, but should work!

@choldgraf
Copy link
Member

I added some documentation about this here: jupyter-book/jupyter-book#1369

@ghutchis
Copy link

Sorry, I've been a bit busy - I edited the sphinx configuration as indicated by @choldgraf At the moment, I don't have the execute 🚀 , download, etc. button / menus. but I found it to be the easiest way to add a header.

I found it was pretty easy to hack the pydata-sphinx theme .. particularly since Bokeh, Fairlearn, etc. have examples you can examine. (e.g., https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/sections.html .. edit the navbar to put the 🚀 back.)

@rabernat rabernat mentioned this issue Mar 1, 2022
Closed
@choldgraf choldgraf mentioned this issue May 9, 2022
Draft
4 tasks
@choldgraf
Copy link
Member

We're now supporting header customization via the pydata sphinx theme, now documented in #677 !

@choldgraf choldgraf mentioned this issue Feb 16, 2023
Merged
1 task
@AllenDowney
Copy link

Thanks to everyone who worked on this!

@casperdcl
Copy link

Can this issue be re-opened?

  • It's not actually fixed. Some other theme (pydata-sphinx-theme) implementing this has nothing to do with this theme (sphinx-book-theme)... unless I'm missing something?
  • I think NEW: Add headers #559 is a "proper" fix, but it's still in draft. Any ETA?

casperdcl added a commit to premAI-io/state-of-open-source-ai that referenced this issue Oct 12, 2023
@casperdcl
add theme & https://ogp.me metadata
28dac1b 
- fixes #63
- fixes #12
- work-around for executablebooks/sphinx-book-theme#182
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
enhancement New feature or request
Projects
None yet
Milestone
No milestone
8 participants
@ghutchis @choldgraf @AllenDowney @chrisjsewell @pradyunsg @jackgerrits @lwasser @casperdcl