Change named headers into subtle links to themselves

[JakobOvrum]

Many sections in the language reference have page anchors, but to know the anchor name one has to look in the source code, effectively rendering them useless.

This change makes these headers links to themselves, so people can easily share links to specific parts of a page.

The links have subtle styling. When not hovering over one, it looks like any other header. Hover over it, and it gets an underline and a pilcrow/paragraph symbol after it.

[JakobOvrum]

Fixed issue where $(GNAME ...) would be affected by the change.

[MartinNowak]

Why changing the color?

[JakobOvrum]

Regular links should be left unchanged, but these anchor links should look like regular headers unless hovered. It's common practice for this kind of feature. Leaving it as the default link color would not only change the colour design of the site, but headers with and without anchor names would have different colouring (which looks rather arbitrary).

I'll add a comment.

[MartinNowak]

Nice, I hope that the increased visibility of anchors will help to add more of them.

[JakobOvrum]

Commented the style. Please have a look and see if you agree with those decisions.

[brad-anderson]

The regular header color with a ¶ is pretty common. See Python's docs. Looks like Node.js uses a # instead but is basically the same (no hover required though). I'd prefer them not stand out compared to other headers because it could just be confusing to some users why some headers are different colors than others (when the color difference means nothing about the content).

[JakobOvrum]

Looking at the Python docs, it looks like they use JavaScript to trigger the visibility of the pilcrow instead of :hover, which allows them to limit the bounds of the link to just the pilcrow symbol. Our JavaScript situation is a bit messy and to avoid a <noscript> path, I think the :hover solution is good for now. However, I liked their idea of having a nice title attribute; pushed that just now.

As for Node.js' permanently visible links; it would probably look a little weird on dlang.org since it's kind of arbitrary which headers have anchors. Or maybe that would be a good thing? ;)

[JakobOvrum]

@9rnsr, what do you think about this?

[9rnsr]

The idea is definitely good. For style issue, I have no opinion.

On the other hand, I have one logical issue - each current anchors are not considered to be displayed (they are internal links just for cross reference). So their name styles are random. For example:

Hyphenate vs underbar:
http://dlang.org/arrays#static-arrays
http://dlang.org/statement#foreach_with_ranges

Singular vs plural:
http://dlang.org/template#alias-template
http://dlang.org/template#function-templates

Section anchor conflicts with the grammar which has same name:
http://dlang.org/expression#Expression

So we need to unify the name styles before publishing them by this change.

[JakobOvrum]

So we need to unify the name styles before publishing them by this change.

You think it's OK to change them one last time? I personally agree we should do that, but I wouldn't be surprised if some people didn't... link breakage is serious, but these links were nigh unobtainable in the first place. I think I'll raise the issue on the NewsGroup.

edit:

http://forum.dlang.org/post/srqvufwxkqguaijwgnuo@forum.dlang.org

[ghost]

Is it possible to set up automatic redirects? E.g. http://dlang.org/template#function-templates redirects to http://dlang.org/template#function-template.

If the answer is yes this would also help out in factoring out the changelog into multiple pages without breaking existing links.

[andralex]

ready to merge?

[andralex]

guess I just will

[JakobOvrum]

No, this was in fact not ready to merge:

So we need to unify the name styles before publishing them by this change.

I was still working on that (actually working on trying to rebase your giant DDoc PR before adding yet more points of breakage).

[JakobOvrum]

I'll open this again after unifying the anchor names.