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: https://github.com/ocaml/odoc/blob/40aa7587a5140a88d77c2ce400f426acf5da79a8/src/html/generator.ml#L115-L118

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" https://github.com/ocaml/odoc/blob/79ee6133dd58ce2891eaa8f8a8de06cf7f9ba76b/src/odoc/etc/odoc.css#L295-L300

[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 https://github.com/ocaml/odoc/pull/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 ?

[yawaramin]

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

Isn't that a simple matter of using relative vs absolute links? If the link is absolute, we can assume it is external.

I will notice in passing that neither docsets for Python, Rust, Haskell, Racket or Scala do these kind of things.

When has OCaml tooling ever followed what the popular languages do? :-) I will mention in passing that, other than Python (EDIT: and Haskell), they all have module indexes in their sidebars, something which has long been asked for in odoc.

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

Are they mutually exclusive?

[dbuenzli]

Isn't that a simple matter of using relative vs absolute links?

No.

[yawaramin]

I just checked, and odoc generates relative paths for all internal links. The only other thing it needs to do is, for link markup like {{: https://example.com} Example.com}, check if the link starts with http:///https://, and generate a rel="external" attribute for those. Then the stylesheet can take care of the colouring.

Note, I am not suggesting target="_blank" with 'opens in new tab' markers, I agree that's a bad idea.

[dbuenzli]

Sigh.

You are not getting it. I may want to link on a document on my website, that's an internal link when I publish the docset on my website that's an external link if the docset is published elsewhere (e.g. on docs.ocaml.org). If the links has to work in all contexts it has to be absolute.

Anyways since:

1. Absolutely no good rationale has been given for distinguishing links.
2. We have proof, for people like @yawaramin who constantly pontificate we should do like programming language X, that other languages docsets do not do this.

It should be entirely sufficient, as already suggested in this comment, to simply classify non-reference links with a custom class and not do anything about it in the default stylesheet.

That way people who want to cripple the reading experience of their users can devise their own stylesheet and do something about it.

[yawaramin]

Sigh. ... You are not getting it.

Well, thank you for finally explaining, after initially posting a one-word answer 'No'.

If the links has to work in all contexts it has to be absolute.

That's a reasonable argument.

for people like @yawaramin who constantly pontificate we should do like programming language X

Was there a need to get personal? Can we stick to the content of the discussion please and not get into who constantly does what?

classify non-reference links with a custom class

That seems reasonable to me. MDN uses <a class="external"> for links pointing outside MDN.

and not do anything about it in the default stylesheet.

Fair enough.

[Julow]

"internal" and "external" links are already separated inside Odoc. External links are written in the documentation with the {{:href} text} syntax, all the other links are internal.

About relative links, they make little sense in Odoc: different backends generate different directory trees, the links are broken when the doc is deployed elsewhere (eg. the new docs site, github pages, odig, dune). If someone needs this, they'll have to open a new issue because Odoc doesn't expect that at all.

About rel="external", I think it might be fine even if the link points to the same domain. domain != site. https://erratique.ch/software/brr can be a different site than https://erratique.ch/software/brr/doc, all it takes is to decide it.

It does. The documentation strings of a package like brr, are heavily linked into MDN web docs and the user will quickly understand that.

brr's documentation contains a lot of references and external links, sometimes several of both in the same paragraph. I didn't saw many links where the target is obvious, the worst offenders are probably "surrogate" and "grapheme clusters", all lower case, which feel like references to sections but are actually external links. I appreciate that links to the doc of Javascript objects are followed by "object", though. Styled external links would definitely have helped me reading the doc.

Can we maybe just close this issue and try to resolve interesting and long standing issues

Absolutely no good rationale has been given for distinguishing links.

This is dismissive of others opinions. If "good" means that you agree with it, indeed, there's none. This is a design change.

[dbuenzli]

I didn't saw many links where the target is obvious,

The point of a link is not to have its target obvious. The point of a link is to make it obvious what information need it is going to answer.

This is dismissive of others opinions. If "good" means that you agree with it, indeed, there's none

Good means something that makes sense for users and producers of documentation. Good design can be justified. I'll repeat one last time, the reasons to do what is proposed here are very weak and I gave good reasons for not doing so. Documentation producers should create good links for their users rather than rely on such visual noise.

But anyways enough time lost here.

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. The main purpose of this is to keep the issue tracker focused to what is actively being worked on, so that the amount and variety of open yet inactive issues does not overwhelm contributors.

An issue closed as stale is not rejected — further discussion is welcome in its closed state, and it can be resurrected at any time. odoc maintainers regularly check issues that were closed as stale in the past, to see if the time is right to reopen and work on them again. PRs addressing issues closed as stale are as welcome as PRs for open issues. They will be given the same review attention, and any other help.

[yawaramin]

If anyone wants to see for themselves how visually distracting the marked-up external links might be, you can use this bookmarklet: https://yawaramin.github.io/bookmarklets/#h2-ext-links

For example, go to https://erratique.ch/software/brr/doc/Brr_canvas/C2d/index.html and run the bookmarklet there. I'm sure some people will be fine with the extra noise and others will find it too distracting.