NEW: Add headers

[choldgraf]

This PR prototypes the addition of header content. This is a new UI element that lives above the sidebar and article header, and can be used to provide more high-level navigation and context for the page.

The elements of the header are populated via a component-style configuration (that we can re-use for the article header as well, once we have settled on a configuration structure). This lets you define the order, behavior, etc of header components in a relatively granular way.

The main use-case this is meant to solve for are cases where organizations have multiple documentation sites that require a consistent style across them (as opposed to the PyData Theme use case, which is a single documentation site with sub-sections). It is inspired by the implementations of a few users of this theme:

• The Dask documentation: docs.dask.org (cc @jacobtomlinson and @jrbourbeau in case they have opinions on this PR)
• The Pythia documentation: https://foundations.projectpythia.org/landing-page.html (cc @kmpaul)
• The 2i2c documentation: https://docs.2i2c.org (cc me 🙃 )
• The QuantEcon theme (cc @mmcky and @AakashGfude )
• The EarthLab learning portal: https://www.earthdatascience.org/courses/ (cc @lwasser)

also cc @rabernat who said some of his projects would benefit from this

Todo

• Any feedback about major functionality or configuration changes
• Write passing tests
• Add launch button support for retrolab
• Add some docs about how you could use this to share theme configuration across projects (e.g. with a YML file or a custom sphinx theme)

closes #182 closes jupyter-book/jupyter-book#1671

[mmcky]

thanks for the ping @choldgraf re: quantecon-book-theme

[Cadair]

Just wanted to say that sunpy are looking at adopting this theme and making a unified top navbar work is a must for us as well, so very excited to see this :)

[choldgraf]

Many thanks @Cadair that is good to hear. If you have any suggestions to guide this functionality, the user API, etc please do share them!

[kmpaul]

Thanks for the ping, @choldgraf! I think this would be an awesome feature that Project Pythia will use. So far, I can't see any design problems with its current form that would prevent us from just using it out of the box. Thanks for doing this!

[nabobalis]

I also wanted to thank you for this! It makes rewriting the theme I am working on much easier!

I do have one request (that I can understand if you decline): I would like to fix the navbar to the top of the viewport with the fixed-top class. Would it be possible to get the classes feature added to the main navbar as well?

I think I can just extend the html using a template if not.

I did notice that adding classes to the buttons (I didn't check dropdowns) added them as o n e t w o instead of one two.

For context, I am trying to replicate:

https://docs.sunpy.org/

We fix the navbar and footer to the viewport (I have the footer simple enough by dropping in a new template).
The navbar is fixed across a range of our documentation builds.

[choldgraf]

@nabobalis I think it should be possible to make the header sticky, but it might take a little bit of work. This is because the article header (the content-level header w/ buttons) is also sticky-top, and it is not trivial to make both of these "stack on top of each other".

One option would be to make this an "either / or" option. You either have a sticky header, or you have a sticky article header. But perhaps we could leave that to a future PR?

[Cadair]

(@nabobalis and I are both working on the sunpy theme at the moment)

I think that I would be ok with the article header not being sticky (or just disabling it in the short term) for our use case, if we can have the top nav be sticky.

Happy for you to leave it to another PR, whatever is easiest for you, we can probably hack around it as Nabil says for a while.

Thanks for all your hard work :)

[kmpaul]

sticky or fixed? Having both the navbar and the content-level header bar fixed-top is possible, as long as you set the css top attribute appropriately with the right offset. We do it in Project Pythia:

https://foundations.projectpythia.org/landing-page.html

I have not tried sticky.

[nabobalis]

Sorry, I should have been clearer! In my current PR that I am working on, before I switched to test this branch.
I created a custom navbar.html and set classes to be navbar fixed-top navbar-expand-lg and in my testing I saw no conflict or behaviour issues with the navbar and article header but since I am quite bad at this, I might have missed it.

[PhilipVinc]

@choldgraf I just noticed this PR and would be interested to try it out once/if it gets to a good stable state.
In fact I had to 'hack' exactly this feature in your theme a few months ago to support our website that is split between Hugo (for the main site) and Sphinx (see here ).

I achieved that by adding a header.html template section, and playing around with the CSS.

Then, I took the same header.html and converted the templating calls to Hugo's language, and plugged it in the main website with almost no changes.

So, I would like to point out that I think it would be useful for projects like ours if the header.html file that defines this header could easily be extracted and used with other generators that are not necessarily Sphinx, or even if you provide some pre-made Hugo/Jekyll sample template.

[pradyunsg]

Close-reopened to retrigger the RTD build.

[nabobalis]

Hello @choldgraf, I was wondering if this branch could be rebased on top of master?

I tried to rebase this on my own fork but as I am too unfamiliar with the codebase, I do not think it is correct.