Mark external links

[kellertuer]

Thanks again for this great package. I use it very often, since as soon as one manages e.g. an API package, it is really nice to be able to link back to the API for further details.

While reading the docs I noticed that it might be nice if one can distinguish internal and external links.
Would it maybe be possible to provide a prefix for external links – either within or directly before a link?
Similarly one could also use a postfix of course.

I for example use something like

[📖 a link](wikipedia-url)

in my docs whenever I link to wikipedia. One could add a similar option to add an emoji upfront to indicate external links – or even separate emojis for the separate external pages one links to?

The most advanced idea would be to use tven the other (external) packages icons, if for example they have fav-icons specified in their docs.

[kellertuer]

@goerz did you have time to take a look? I think something like the favicon of the other package (if available) would be a great default or a generic external-link-icon.

[goerz]

I think this is probably out of scope.

The way to do this is via CSS. See Stack Overflow for how to:

a[href]:not(:where(
  /* exclude hash only links */
  [href^="#"],
  /* exclude javascript only links */
  [href^="javascript:" i],  
  /* exclude relative but not double slash only links */
  [href^="/"]:not([href^="//"]),
  /* domains to exclude */
  [href*="//stackoverflow.com"],
  /* subdomains to exclude */
  [href*="//meta.stackoverflow.com"],
)):after {
  content: '↗️';
}

So you just set up something like that in the custom CSS for Documenter.

What might make this a little easier is if the HTML generated by @extref links had CSS classes that mark them as external links. That's something I'm very much open to, but it would be difficult: I'm only generating nodes in the Markdown syntax tree, and then that gets translated to HTML separately. So MarkdownAST would have to support the feature. That's probably not feasible in the near future, so I'd tentatively close this issue. If it becomes possible, we can reopen it.

What I'm not really up for is literally injecting images or emojis into the link text. That just feels very wrong, and most likely has accessibility issues: screenreaders can separate out the CSS, but actually modifying the content is a different matter.

[kellertuer]

maybe css classes with external links and a class name the same as the external package name would be great, yes

and sure, pure injection would not be nice, a proper html-class stuff and css is the right way to go for sure.

[goerz]

Just to emphasize: Even without adding custom classes and all that: CSS already has the capabilities to do everything you want. The "filtering" capabilities of matching <a> tags based on regex-pattern in the href attributes is extremely powerful. You can set specific icons for specific target domains, a general fallback for external references, and so forth. Of course, it's a bit of work to write out all of that CSS, but it's not really different (maybe just a little more brittle) from writing out the same kind of CSS based on hypothetical custom classes.

[kellertuer]

Will try, maybe a good CSS exercise for a calm evening closer to Christmas :) Will report the result here.

[goerz]

And you should definitely also do that for your existing Wikipedia links. Like I said, I think [📖 a link](wikipedia-url) is a bit of an accessibility issue. Much better to make a CSS rule for matching all links pointing to Wikipedia and have that inject the book emoji in the rendered output.

[kellertuer]

Sure, I did just not think of the css approach when typing markdown back then. Also my CSS is a bit rusty, last time I worked with that is at least 10 years ago.

[goerz]

This is the kind of thing where ChatGPT and its cousins excel! 😉

Before I even googled the solution to find the StackOverflow link in #13 (comment):

🧑:
How do I display a little icon in front of every external link, using CSS?

🤖:[ChatGPT4]
You can use the CSS `::after` pseudo-element to display an icon after each external link. Here's a method to accomplish this:

1. First, check that the link is external by selecting links that don't match your site's domain.
2. Use `::after` to add content after these links.

Here's an example:

```css
a[href^="http"]:not([href*="yourdomain.com"])::after {
    content: url('your-icon.png');
    display: inline-block;
    width: 16px; /* Adjust size as needed */
    height: 16px; /* Adjust size as needed */
    margin-left: 4px; /* Space between text and icon */
}
```

This CSS rule applies to all `<a>` elements that have an `href` starting with "http" but do not contain your site's domain. Adjust `'your-icon.png'` as needed for your specific icon. Make sure the image URL is correctly pointed to the image resource you want to display.

[kellertuer]

I think the main problem I am struggling with is the relative path to a logo, the rest seems ok.

edit: Ah ChatGPT could help again. I will mention you in the PR just in case you want to refer to that in the docs here maybe.

[goerz]

Very nice!

Yes, I think I’ll add that as a tip to the documentation here, at some point. Reopening the issue, to track that…

[kellertuer]

Well, thanks for the hints in the right directions :)
I think it is quite nice to see where functions / topics come from, hence the idea.

For now just the switch based on the theme light/dark is not fully complete and I copied over the logos myself. That could maybe be improved.