BUG: anchor links hidden by header navbar when this has a different height

[jorisvandenbossche]

Reported by numpy at numpy/numpy#17207. Anchor links jump to a slight wrong place, so that the heading is a bit hidden by the navbar. Eg https://numpy.org/devdocs/user/building.html#accelerated-blas-lapack-libraries right now gives:

I suppose this happens for the numpy docs because they set their navbar (for having a larger logo) to be a bit bigger: 75px instead of the 45px in the default theme.
And then the margin added to headings to add an offset to the anchor link to appear just below the navbar doesn't match anymore.

Some related issues: #6, #147 (and linked PRs)

[eric-wieser]

I'm not really sure this is a theme bug. Perhaps there's a feature request here to allow explicit customization of the header height; but numpy should have no reason to expect it to be possible to apply random CSS dimensions to various objects and expect everything else to work.

[choldgraf]

yeah I agree it's not a bug if it required them to manually change the CSS in order to cause this behavior. Perhaps something we should document though (and as @eric-wieser suggests leave as a feature implementation to allow for different-sized headers)

[mattip]

And then the margin added to headings to add an offset to the anchor link ...

Thanks, I agree this is self-afflicted.
Which margins are these? I would be happy to modify this for NumPy, if I knew where the value was.

[jorisvandenbossche]

Indeed, "bug" was maybe the wrong term, but I think it would still be a nice feature that users of the theme can change the height of the navbar more easily without running into this (or having to change a different marging as well).

Which margins are these? I would be happy to modify this for NumPy, if I knew where the value was.

I think it is styled by this headerstyle (but for overriding it in custom css, I think you need to override it for h1, h2, h3, etc, as this headerstyle is automatically added to those in the scss compilation):

https://github.com/pandas-dev/pydata-sphinx-theme/blob/15819a8373c7fffa700cd9c5cd9c3531889aece8/src/scss/_base.scss#L46-L59

Something like

h1, h2, h3, h4, h5, h6 {
    margin: 3.5rem 0 1.05rem;
}

h1::before, h2::before, h3::before, h4::before, h5::before, h6::before {
    height: 100px;
    margin: -120px 0 0;
}

might do (based on some experimentation, I increased the top margin of hX, and also increased height and negative margin of hX:before, but to really explain/understand it would need to dive in a bit more)

[choldgraf]

why not make the header size a CSS-controllable variable per #190 ?

[jorisvandenbossche]

why not make the header size a CSS-controllable variable per #190 ?

Ideally certainly yes, but then somebody first needs to understand how to translate the navbar height into those 3 margin/height numbers in the snippet above ..

[hoetmaaiers]

I am considering to add a theme css variable --header-height which in combination with PR #280 fixes this bug #punintented ;)

Would this work for the Numpy people?

[jorisvandenbossche]

I think a variable should be fine (assuming that this will then allow the logo to expand automatically to the available space by a larger height).

Also, it would be nice that the changes made for this, could also work for the case where there is no header (eg https://clustergram.readthedocs.io/en/latest/), so you can set the header-height to 0 in such a case.

[choldgraf]

lol wow the pydata-sphinx-theme without a header looks a lot like Jupyter Book. I guess that's no coincidence 😅

[mattip]

Would this work for the Numpy people?

Yup, that would be great