Farai → Bikeshed → Components

`render-link.html`

This render hook builds off of Hugo’s built-in one and provides robust linking to pages and site assets. To this I made following changes:

Trimming /content/ from the .Destination so I can reference files in the structure it appears in VS Code.
Add a warning in case a referenced page or asset doesn’t exist, pointing to the offending file.
Added support for attributes specified as a JSON object in the markdown title.
Allowed for linking to alternate output formats by specifying the outputFormat in the title’s attribute list.

Note that this preserves query strings and link fragments. Note that you can specify an href attribute and it will take presidence over the url specified in the markdown link’s href.

Sample Usage

Basically

[Link Text](href 'attributes')

where the attributes is a JSON object wrapped in single quotes.

This very page where the link is in a different font.

[This very page where the link is in a different font.](/content/bikeshed/components/render-link.md '{"style":"font-family: serif"}')

This site’s RSS fees which is specified as an alternative output format of the home page

[This site's RSS fees which is specified as an alternative output format of the home page](/_index.md '{"outputFormat":"rss"}')

Source Code

{{- $attributes := .Attributes -}}
{{- $options := dict
  "outputFormat" "html"
-}}
{{- with .Title -}}
    {{- if hasPrefix . `{` -}}
        {{- $attrObj := transform.Unmarshal . -}}
        {{- range $k, $v := $attrObj -}}
            {{- if or (isset $options $k) (eq $k "lang") -}}
              {{- $options = merge $options (dict $k $v) -}}
            {{- else -}}
              {{- $attributes = merge $attributes (dict $k $v) -}}
            {{- end -}}
        {{- end -}}
    {{- else -}}
        {{- $attributes = merge $attributes (dict "title" . ) -}}
    {{- end -}}
{{- end -}}
{{- $u := urls.Parse .Destination -}}
{{- $href := $u.String -}}
{{- if strings.HasPrefix $u.String "#" }}
  {{- $href = printf "%s#%s" .PageInner.RelPermalink $u.Fragment }}
{{- else if not $u.IsAbs -}}
  {{- $path := strings.TrimPrefix "./" $u.Path }}
  {{- $path := strings.TrimPrefix "/content" $u.Path }}
  {{- with or ($.PageInner.Resources.Get $path) (resources.Get $path) -}}
    {{- $href = .RelPermalink -}}
  {{- else with $.PageInner.RelRef (dict "path" $path "outputFormat" $options.outputFormat) -}}
      {{- $href = . -}}
  {{- else -}}
    {{- if $.PageInner.File -}}
      {{- warnf "Link %s referenced in %s not found." $.Destination $.PageInner.File.Filename -}}
    {{- else -}}
      {{- warnf "Link %s not found." $.Destination -}}
    {{- end -}}
  {{- end -}}
  {{- with $u.RawQuery -}}
    {{- $href = printf "%s?%s" $href . -}}
  {{- end -}}
  {{- with $u.Fragment -}}
    {{- $href = printf "%s#%s" $href . -}}
  {{- end -}}
{{- end -}}
{{- if not (isset $attributes "href") -}}
    {{- $attributes = merge $attributes (dict "href" $href) -}}
{{- end -}}
<a
  {{- range $k, $v := $attributes -}}
    {{- if $v -}}
      {{- printf " %s=%q" $k $v | safeHTMLAttr -}}
    {{- end -}}
  {{- end -}}
  >{{ .Text | safeHTML }}</a>
{{- /**/ -}}

TODO

Add render link support for alternate content formats.