Sticky headers hide the anchor links text

[javiereguiluz]

As reported by @weaverryan when you click on any anchor link (e.g. http://symfony.com/doc/current/book/controller.html#requests-controller-response-lifecycle) the sticky headers hide the text of this link and the result is pretty bad for website visitors.

I tried to fix this issue using some techniques explained in this StackOverflow question but none of them was successful.

The main problem in our case is that the usually hidden anchor link (a.headerlink) is visible for us:

<h2>
  Requests, Controller, Response Lifecycle
  <a class="headerlink" href="#requests-controller-response-lifecycle"
        title="Permalink to this headline">
    ¶
  </a>
</h2>

Could anyone please help us solving this issue? Thanks!

[stof]

the element needing the offsetting is not the link a.headerlink you have here. It is the target element with the id requests-controller-response-lifecycle.

The issue is that these ids are rendered on a visible div, so the fix does not apply either (but the first child of each such div is an empty span with the id index-* so maybe there is something to do in the Sphinx theme to improve it)

[javiereguiluz]

@stof you are absolutely right and I feel ashamed for having misunderstood these techniques so badly.

Now we can make anchors visible again:

But this have a pretty serious drawback:

To make it work, the anchor adds a big gap before itself. As this gap is only applied to the given anchor and not to the other page contents, the result is not visually pleasant.

So we are still looking for a good solution to this problem.

[wouterj]

@javiereguiluz who put the id on the heading? Are you doing it in the theme or is it done by Sphinx automatically? It would be easier if you added it to the span element that also has the index anchor. Then you can only move that span element x px up and nobody discovers it :)

[javiereguiluz]

@wouterj I always try to avoid messing with Sphinx. Apparently we have fixed the problem without modifying the HTML contents. This is the only solution that worked for us: http://stackoverflow.com/a/11842865

Hopefully this will be deployed soon and we could test it thoroughly.

[wouterj]

@javiereguiluz does this also work when using the #index-N anchors? They are used by the glossary for instance

[javiereguiluz]

@wouterj very good catch! We've just also fixed the anchors for the Symfony Glossary (although the format of the anchors is #term-xxxx instead of #index-N).

[stof]

well, there are also some index-N anchors (which may be used by the doc index rather than the glossary)

[javiereguiluz]

@stof @wouterj that's right! Some unnamed anchors have the index-N format. I've checked and everything works right now (at least locally). I've also added the "Symfony Index" link back to the documentation section sidebar.

If you can think of any other special doc section or page where anchors could fail, please tell me before deploying these changes. Thanks!

[javiereguiluz]

@stof @wouterj the solution has now been deployed and you can check it out live at symfony.com If you think that this problem is solved, please close this issue. Thanks.

[wouterj]

@javiereguiluz great!

However, it doesn't work for 2 edge cases currently:

• Sidebar anchors: http://symfony.com/doc/current/book/installation.html#book-installation-permissions
• Anchors without a headline: http://symfony.com/doc/current/book/security.html#book-security-template-expression (it should link to the versionadded directive)

(btw, did you recieve my second email last week?)

[wouterj]

ping @javiereguiluz

[javiereguiluz]

@wouterj thanks for reporting these errors. They have been added to our backlog.

[wouterj]

@javiereguiluz another (minor) problem: The anchor link now already get the hover effect when you're 80px above the headline (because the highlight has a margin-top of -5em (which is around 80px))

[wouterj]

@javiereguiluz found another edge case which isn't supported yet: links to footnotes http://symfony.com/doc/current/contributing/code/bc.html#id54