Feature Request: different style for external and internal links

[impossiblynew]

Please remove this if this is not the appropriate avenue for a feature request.

I am currently writing a library that contains a lot of links to external resources, and I notice that while navigating my documentation that it's irritating how easy it is to accidentally click a link that sends you to a new page when you though you were just going to be navigated to a different part of the documentation.

Would it be possible to style external links differently in such a way as to make it obvious before clicking whether the link is internal or external?

[asavahista]

for anyone that wants to pick this up, this is probably the place you'd want to change:

odoc/src/html/generator.ml

Lines 115 to 118 in 40aa758

	| Link (href, c) ->
	let a = (a :> Html_types.a_attrib Html.attrib list) in
	let content = inline_nolink ~emph_level c in
	[ Html.a ~a:(Html.a_href href :: a) content ]

it may be best to implement it as a class and use an ::after pseudo-selector to add a symbol (svg using currentColor?) representing "external link"

odoc/src/odoc/etc/odoc.css

Lines 295 to 300 in 79ee613

	.xref-unresolved {
	color: #2C94BD;
	}
	.xref-unresolved:hover {
	box-shadow: 0 1px 0 0 var(--xref-shadow);
	}

[Julow]

it may be best to implement it as a class and use an ::after pseudo-selector to add a symbol (svg using currentColor?) representing "external link"

Sounds reasonable. Contributions are welcome :)

[asavahista]

not sure if this should also be implemented (or an option) for the latex generator.

also not sure where to source the icons - font awesome sounds like a safe bet but not sure if the license is acceptable

[Julow]

External links are already formatted specifically in latex:

\href{my\_url}{my\_url}\footnote{\url{my\_url}}

Their license is the most permissible possible, it'll work with Odoc. It's also self-contained, no license work needed at all:

Downloaded Font Awesome Free files already contain embedded comments with sufficient attribution, so you shouldn't need to do anything additional when using these files normally.

Odoc has a command that writes the static files (odoc support-files, currently only the CSS file) but I'd prefer if the icon could be inlined into the CSS to avoid a request for such a small file.

[dbuenzli]

Personally I find the whole premise behind "external link"s dubious. There's no such thing as an "external link", there's a hypertext that's all.

For one thing an "external link" is contextual. It may not be one depending on where docsets are published.

Second the justification for this request is:

I notice that while navigating my documentation that it's irritating how easy it is to accidentally click a link that sends you to a new page when you though you were just going to be navigated to a different part of the documentation.

If the links you are making are irritating or do not lead where the reader expected to answer her question then it seems to me that you designed a bad linking user experience.

I'd rather suggest to close this feature request as won't fix.

---

P.S. This reminds me of clients which always want to cripple the web experience of their users by having "external links" open in a new tab – or have a modal warning that you are leaving their site – because they think their website is the center of the universe. It always takes a bit of time to explain.

[Julow]

P.S. This reminds me of clients which always want to cripple the web experience of their users by having "external links" open in a new tab – or have a modal warning that you are leaving their site – because they think their website is the center of the universe. It always takes a bit of time to explain.

I agree with this. And that's why I think a marker for external links is a nice solution. The difference between a "internal link" or "external link" matters to reader of the doc, the fact that web standards don't care is irrelevant. We have markers on "external links" for decades on forums.

[dbuenzli]

The difference between a "internal link" or "external link" matters to reader of the doc, the fact that web standards don't care is irrelevant.

Why does it matter ?

And that's why I think a marker for external links is a nice solution.

That doesn't answer the question: what is the problem ?

We have markers on "external links" for decades on forums.

Doesn't mean it's a good idea. Is there one on discuss.ocaml.org ? No.

[Julow]

Why does it matter ?

It avoids disturbing reading strategy (eg. maybe read the external links first or last), allows to interpret the URL before clicking more easily, expects what you'll see on the next page so there's no surprise once the page loads.
There's so many links on a documentation page, I think marking some of them can't hurt.

Doesn't mean it's a good idea.

I mean, it's solving the issue without making "their website is the center of the universe" and doesn't "cripple the web experience".

[dbuenzli]

It avoids disturbing reading strategy (eg. maybe read the external links first or last),

I don't see how following an external versus an internal link "disturbs the reading strategy". You follow a link to satisfy an information need. The fact that it is internal or external to the docset is irrelevant. The point is to make the good link for your reader.

Again the whole premise of making a difference between external and internal links is wrong. Except for marketing and branding bullshit I never saw any good reason for it, and have yet to be shown one.

There's so many links on a documentation page, I think marking some of them can't hurt.

It does. The documentation strings of a package like brr, are heavily linked into MDN web docs and the user will quickly understand that. The only effect of #767 will be to fill the docstrings with pointless icons glued to text that disturbs the reading flow.

The only thing that PR manages is to add pointless visual noise to the documentation.

[asavahista]

tl;dr please understand that there are people who do want it, and that it exists for a good reason, so at least consider making it an option
(alternatively, someone could try gauging community opinion elsewhere)

do note that there is a very good reason for it! in general (for docs and encyclopedias) an external link generally leads, to, not docs/not articles, which is not useful if the reader is here for docs.

one important difference between internal and external links is that it's less easy to navigate from the external site back to the docs, especially if you're several links deep into the external site. i'm sure this is also the reason why they open in a new tab

and of course if we're talking about the ocaml discourse:

• do note it also has noise (the badge showing number of times clicked)
• i believe forums are different since generally they aren't expected to be extensively internally linked

[dbuenzli]

i'm sure this is also the reason why they open in a new tab

You deciding for users when to open a new tab in their browser is just bad user experience. Users perfectly know how to do this by themselves when they feel the need for it.

do note that there is a very good reason for it! in general (for docs and encyclopedias) an external link generally leads, to, not docs/not articles, which is not useful if the reader is here for docs.

Still not a good reason. Very often in docs external links link to other relevant docs or references needed for understanding. I feel like I'm repeating myself but your link content should make it clear what you are going to link to, not an arbitrary distinction between docset references and "external" links, which depending on where your docset is going to be published may well not be.

I don't mind classifying the links if you want to do these things but I'm definitively against the default stylesheets doing anything about it because in general it's just plain absurd.

[yawaramin]

Here is my suggestion for external links: <a href="..." rel="external">...</a>

And make external links a different colour than internal links, perhaps pink. Easy to do in CSS. I'm not strongly attached to a colour.

The rel="external" value is a valid way to semantically mark external links, per:

• https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-rel
• https://developer.mozilla.org/en-US/docs/Web/HTML/Link_types

For those with colour perception issues, the fallback of the rel attribute should help, when paired with an assistive technology.

[dbuenzli]

The rel="external" value is a valid way to semantically mark external links,

Except that if you link on the website on which you publish the docset that's a wrong semantics.

Since it seems people usually mostly want to do like programming language X rather than think and design by themselves, I will notice in passing that neither docsets for Python, Rust, Haskell, Racket or Scala do these kind of things.

Can we maybe just close this issue and try to resolve interesting and long standing issues for odoc, like proper image or mathjax support ?