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

[wouterj]

@javiereguiluz I keep pinging you here, another case which isn't fixed is in blog posts: http://symfony.com/blog/security-releases-symfony-2-0-24-2-1-12-2-2-5-and-2-3-3-released#cve-2013-4752-request-gethost-poisoning

[wouterj]

ping @javiereguiluz, it looks like all problems in this article are back now and the bug fix is reverted. Is there anything we can do to help you?

[javiereguiluz]

@wouterj this problem indeed returned to its original situation because we needed to fix another design problem. I'm going to fix this issue for once and for all, but I need a bit of time because it has to work right for every page and for every device (some solutions suggested by some commenters of this repository didn't work for all devices and all pages). I'm on it but it will take some time.

[javiereguiluz]

Hopefully, this long-standing problem has been solved. I've tested it in the documentation section and in the blog. Everything seems to work as expected. If you agree, please close this issue. If not, please provide more details about the error. Thanks.

[wouterj]

@javiereguiluz the headlines look great in the docs and blog. However, you've missed these edge cases I found:

• 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)
• Footnotes http://symfony.com/doc/current/contributing/code/bc.html#id54

[javiereguiluz]

@wouterj I'm glad to inform you that this annoying problem has been fixed even for the edge cases that you found. The website will now scroll via JavaScript to the right anchor link. Everything will be online soon after the next website deploy.

[javiereguiluz]

@wouterj the website is now deployed and all these issues have been fixed. If you agree, let's close this issue.

[wouterj]

Nice animation!

[xabbuh]

I'm wondering if I am the only one who still has issues with the sticky headers. Visiting http://symfony.com/doc/current/book/installation.html#book-installation-permissions looks like this for me (using Firefox 34):

[javiereguiluz]

@xabbuh this is what should happen: the page smoothly scrolls to the location of the anchor link once the page is loaded. Here it is a GIF showing it in action on my computer:

In order to work, this needs JavaScript and the page must be completely loaded. Please check if there is any error in the browser inspector. Thanks.

[xabbuh]

@javiereguiluz There are no JavaScript errors and no failures for the files being loaded. Strangely enough, it works with Chrome 39.

[xabbuh]

@javiereguiluz I checked this again. When using Chrome everything works as expected. Using Firefox doesn't work though (I tested this on different systems and even with a fresh profile). Furthermore, clicking on one of the table of contents items on the left sight doesn't work either.

[javiereguiluz]

@xabbuh thanks again for reporting and investigating this problem. I can confirm that the problem existed and it's been fixed. Now it must be merged, deployed, etc.

The problem was that animate doesn't work with scrollTop on Firefox the same way as other browsers. The solution was found here:

// works everywhere except on Firefox
$('body').animate({ scrollTop: ... });

// works everywhere
$('html, body').animate({ scrollTop: ... });

[xabbuh]

@javiereguiluz Thank you! I'll check again when the fix is deployed and will close here then.

[stof]

@javiereguiluz any idea when this will be deployed ? It is annoying

[javiereguiluz]

@stof I know that the changes have already been merged on symfony.com code but I don't control the deployment process, so I can't really say anything else. I'm sorry.

[javiereguiluz]

@stof @xabbuh I have good news for you! The fixes have been deployed and now everything works as expected. If you agree, please close this issue. Thanks!

[xabbuh]

Thank you @javiereguiluz ❤️ It now works as expected. 😃

[xabbuh]

even the edge case @wouterj listed in #3974 (comment)