Review external links

[cmjc]

Description

External links should consistently open in new browser tabs and there should be a visual cue to the reader that the link is to an external site.

Solution

Customise the markdown rendering using Hugo/Docsy customisation techniques to open the page in a new tab and display a glyph indicating external navigation.

There may be other approaches, such as using shortcodes. Example: https://stackoverflow.com/questions/72820972/hugo-how-to-create-a-link-to-page-in-a-shortcode

Rationale

• visual cue: provides a commonly-used indication that a hyperlink will navigate to an external site
• open in new tab: to avoid losing local context, it is convenient if an external site opens in another browser tab.

Implementation

Interesting references are:

• https://www.porchlab.com/hugo/hugo-external-links-new-tab/
• https://gohugo.io/templates/render-hooks/
• Manual links:
  • https://github.com/google/docsy/pull/511/files
  • https://www.docsy.dev/docs/adding-content/navigation/#add-manual-links-to-the-section-menu

[cmjc]

Docsy sites seem to be very bad at this and (a) commonly an external site opens in same not a new window, (b) to use more often than not an HTML anchor syntax.

For example:

https://github.com/google/docsy-example/blob/2112cfb04b3b7ae0aaaaec7e3724211122884af7/content/en/about/_index.html#L19

{{% blocks/lead %}}
Goldydocs is a sample site using the <a href="https://github.com/google/docsy">Docsy</a> Hugo theme that shows what it can do and provides you with a template site structure. It’s designed for you to clone and edit as much as you like. See the different sections of the documentation and site for more ideas.
{{% /blocks/lead %}}

If this was getting an external hyperlink in the menu, this approach could be used in the config file: https://github.com/google/docsy/blob/096aa627f07765e52fcad2831e1e477e24f89780/userguide/hugo.yaml#L22

A promising solution seems to be to use a renderhook and for the visual cue the Font Awesome external link glyph (see https://fontawesome.com/v5/icons/external-link-alt?f=classic&s=solid) to pull in the font awesome glyph. Could then use either an anchor or standard md form. Example:

<a href="https://docs.autonity.org/delegators/bond-stake/" >Bond and unbond stake <i class="fas fa-external-link-alt"></i></a>

[ Bond and unbond stake <i class="fas fa-external-link-alt"></i>](https://docs.autonity.org/delegators/bond-stake/)

To investigate further.

[cmjc]

OK, so the render hook approach, cf:

• https://gohugo.io/templates/render-hooks/#context-passed-to-render-link-and-render-image
• implementation - per https://www.porchlab.com/hugo/hugo-external-links-new-tab/#implementation

This can be used to make external links open in a new window that are (a) cleartext hyperlink and (b) Standard Markdown []() syntax.

This can then be done as a simple customisation to override the default Docsy layouts so:

• edit config.toml to explicitly specify Goldmark as the default Markdown renderer:

  [markup]
  [markup.goldmark]
  [markup.goldmark.renderer]
    unsafe = true

  (Why is unsafe = true?! See https://github.com/rstudio/blogdown/issues/447 and the referenced hugo issue https://github.com/gohugoio/hugo/issues/6581)

• add ./layouts/_default/markup/render-link.html directory hierarchy, and,

• add template specification:

<!--layouts/_default/_markup/render-link.html-->
<a href="{{ .Destination | safeURL }}"{{ with .Title }} title="{{ . }}"{{ end }}{{ if strings.HasPrefix .Destination "http" }} target="_blank" rel="noopener"{{ end }}>{{ .Text | safeHTML }}</a>

Note: modifying to explicitly set noopener for security reason cited here: https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/noopener , which links to here: https://mathiasbynens.github.io/rel-noopener/.

However, I can't figure out how to include the glyph in the template, so it still needs to be explicitly specified.

This gives then 3 options to get the new window and the glyph:

1. Ignore render-hook and simply specify as html a syntax. So:

   <a href="https://docs.autonity.org/delegators/bond-stake/" target="_blank" >Bond and unbond stake <i class="fas fa-external-link-alt"></i></a>

Opens in new window, glyph part of live link.

2. Combine with render-hook template and explicitly specify the glyph:
   • Cleartext hyperlink, opens in new window:

     https://docs.autonity.org/delegators/bond-stake/ <i class="fas fa-external-link-alt"></i>]()` with glyph specified[Bond and unbond stake <i class="fas fa-external-link-alt"></i>

Opens in new window, glyph is NOT part of live link.

3. Standard Markdown [ <i class="fas fa-external-link-alt"></i>]():

       [Bond and unbond stake <i class="fas fa-external-link-alt"></i>](https://docs.autonity.org/delegators/bond-stake/)

Opens in new window, glyph part of live link.

Options 1 & 3 are looking preferable atm.