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

NEW: Add headers #559

Draft
wants to merge 17 commits into
base: master
Choose a base branch
from
Draft

Conversation

choldgraf
Copy link
Member

@choldgraf choldgraf commented May 9, 2022

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:

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

mmcky commented May 10, 2022

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

@Cadair
Copy link

Cadair commented May 12, 2022

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

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

kmpaul commented May 16, 2022

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

nabobalis commented May 17, 2022

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

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

Cadair commented May 17, 2022

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

kmpaul commented May 17, 2022

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

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

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

Close-reopened to retrigger the RTD build.

@pradyunsg pradyunsg closed this Jun 1, 2022
@pradyunsg pradyunsg reopened this Jun 1, 2022
@nabobalis
Copy link

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.

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

Successfully merging this pull request may close these issues.

Launch in Binderhub RetroLab environment Allow for header customization
7 participants