Refactor link partial and shortcode

data/structures/link.yml

@@ -0,0 +1,74 @@
+comment: >-
+  Generates a link for a given named link or url. The shortcode supports a
+  single unnamed parameter, or various named parameters. The unnamed parameter
+  is recognized as a url if it starts with "http", else it is treated as either
+  a named link or internal reference (in that order). Any inner text is rendered
+  as the link title, otherwise it uses the host name (for external links), link
+  title (for internal links), or anchor name (for any local references
+  containing a "#").
+arguments:
+  page:
+    type:
+      - '*hugolib.pageState'
+      - '*hugolib.pageForShortcode'
+    optional: false
+    group: partial
+    comment: Context of the current page.
+  destination: 
+    type: string
+    optional: false
+    group: partial
+    comment: >-
+       Target destination.
+  href: 
+    type: string
+    position: 0
+    optional: true
+    comment: >-
+       Reference to either an external link (if it starts with http), a named
+       link (if it can be found in params.links), or internal reference.
+       Both external and internal references may include an anchor "#".
+  name:
+    type: string
+    optional: true
+    comment: Alias of href.
+  url:
+    type: string
+    optional: true
+    comment: Alias of href.
+  cue:
+    type: bool
+    optional: true
+    comment: >-
+      Flag to indicate if an external link should show a visual cue, defaults to
+      setting "main.externalLinks.cue" in the site's parameters.
+  tab:
+    type: bool
+    optional: true
+    comment: >-
+      Flag to indicate if an external link should open in a new tab, defaults to
+      setting "main.externalLinks.tab" in the site's parameters.
+  case:
+    type: bool
+    optional: true
+    default: true
+    comment: >-
+      Flag to indicate if the retrieved title (e.g. no inner text is provided)
+      of an internal link should use its original case. If false, the title is
+      set to lower case.
+  class:
+    type: string
+    optional: true
+    comment: Class attribute of the anchor element.
+  text:
+    type:
+      - string
+      - template.HTML
+    optional: true
+    group: partial
+    comment: Link title.
+body:
+  type: string
+  optional: true
+  group: shortcode
+  comment: Link title.

layouts/partials/utilities/link.html → layouts/partials/assets/link.html

@@ -1,9 +1,20 @@
+<!-- 
+    Copyright © 2023 The Hinode Team / Mark Dumay. All rights reserved.
+    Use of this source code is governed by The MIT License (MIT) that can be found in the LICENSE file.
+    Visit gethinode.com/license for more details.
+-->
+
+{{ $error := false -}}
+
+<!-- Validate arguments -->
+{{ if partial "utilities/IsInvalidArgs.html" (dict "structure" "link" "args" . "group" "partial") }}
+    {{ errorf "partial [assets/link.html] - Invalid arguments" -}}
+    {{ $error = true }}
+{{ end }}
+
+<!-- Initialize arguments -->
 {{ $destination := .destination }}
-{{- if not $destination -}}
-    {{- errorf "partial [utilities/link.html] - Missing param 'destination'" -}}
-{{- end -}}
 
-{{- $error := false -}}
 {{- $target := "" -}}
 {{- $rel := "" -}}
 {{- $case := .case | default true }}
@@ -15,6 +26,7 @@
 {{- $text := .text -}}
 {{- $class := .class -}}
 
+<!-- Main code -->
 {{- if $isExternal -}}
     {{- if not $text -}}
         {{- $text = (urls.Parse (absURL $destination)).Host -}}
@@ -33,7 +45,7 @@
     {{- if strings.Contains $destination "#" }}
         {{ $segments := split $destination "#" }}
         {{- if ne (len $segments) 2 }}
-            {{- errorf "partial [utilities/link.html] - Malformed path, expected one anchor '#' only: %s" $destination -}}
+            {{- errorf "partial [assets/link.html] - Malformed path, expected one anchor '#' only: %s" $destination -}}
         {{ else }}
             {{- $destination = index $segments 0 -}}
             {{- $anchor = index $segments 1 -}}
@@ -42,7 +54,7 @@
 
     {{ $ref := partial "utilities/GetPage.html" (dict "url" $destination "page" $page) }}
     {{- if not $ref -}}
-        {{- errorf "partial [utilities/link.html] - Cannot find page: %s" $destination -}}
+        {{- errorf "partial [assets/link.html] - Cannot find page: %s" $destination -}}
         {{- $error = true -}}
     {{- else -}}
         {{- $destination = $ref.RelPermalink -}}

layouts/partials/assets/sidebar.html

@@ -71,7 +71,7 @@
                 <li>
                     {{ $class := "sidebar-item text-decoration-none rounded" }}
                     {{ if $active }}{{ $class = printf "%s active" $class }}{{ end }}
-                    {{ $link := partial "utilities/link.html" (dict "destination" $href "text" $title "class" $class "page" $page) }}
+                    {{ $link := partial "assets/link.html" (dict "destination" $href "text" $title "class" $class "page" $page) }}
                     {{ if $link }}
                         {{ print $link | safeHTML }}
                     {{ else }}
@@ -84,7 +84,7 @@
         <li>
             {{ $class := "sidebar-item text-decoration-none rounded small" }}
             {{ if $active }}{{ $class = printf "%s active" $class }}{{ end }}
-            {{ $link := partial "utilities/link.html" (dict "destination" $href "text" $title "class" $class "page" $page) }}
+            {{ $link := partial "assets/link.html" (dict "destination" $href "text" $title "class" $class "page" $page) }}
             {{ if $link }}
                 {{ print $link | safeHTML }}
             {{ else }}

layouts/partials/footer/footer.html

@@ -5,7 +5,7 @@
             {{ cond (gt (len .Site.Copyright) 0) .Site.Copyright $copyright }}
             {{ .Site.Params.footer.license | safeHTML }}
             {{ if .Site.Params.main.endorse }}
-                {{ $link := partial "utilities/link" (dict "destination" (index site.Params.links "hinode") "text" "Hinode" "class" "link-bg-footer") }}
+                {{ $link := partial "assets/link.html" (dict "destination" (index site.Params.links "hinode") "text" "Hinode" "class" "link-bg-footer" "page" .Page) }}
                 {{ T "poweredBy" $link | safeHTML }}
             {{ end }}
         </small>

layouts/partials/single/thumbnail.html

@@ -9,14 +9,14 @@
     {{- $thumbnail = $page.Params.Thumbnail.url -}}
     {{- $author := "" -}}
     {{- if and $page.Params.Thumbnail.authorURL "text" $page.Params.Thumbnail.author }}
-        {{- $author = partial "utilities/link" (dict "destination" $page.Params.Thumbnail.authorURL "text" $page.Params.Thumbnail.author) -}}
+        {{- $author = partial "assets/link.html" (dict "destination" $page.Params.Thumbnail.authorURL "text" $page.Params.Thumbnail.author "page" $page) -}}
     {{- else if $page.Params.Thumbnail.author }}
         {{- $author = $page.Params.Thumbnail.author -}}
     {{- end -}}
 
     {{- $origin := "" -}}
     {{- if and $page.Params.Thumbnail.originURL "text" $page.Params.Thumbnail.origin }}
-        {{- $origin = partial "utilities/link" (dict "destination" $page.Params.Thumbnail.originURL "text" $page.Params.Thumbnail.origin) -}}
+        {{- $origin = partial "assets/link.html" (dict "destination" $page.Params.Thumbnail.originURL "text" $page.Params.Thumbnail.origin "page" $page) -}}
     {{- else if $page.Params.Thumbnail.origin }}
         {{- $origin = $page.Params.Thumbnail.origin -}}
     {{- end }}

layouts/shortcodes/link.html

@@ -1,24 +1,18 @@
 <!-- 
-    Generates a link for a given named link or url. The shortcode supports a single unnamed parameter, or various named
-    parameters. The unnamed parameter is recognized as a url if it starts with "http", else it is treated as either a
-    named link or internal reference (in that order). Any inner text is rendered as the link title, otherwise it uses
-    the host name (for external links), link title (for internal links), or anchor name (for any local references
-    containing a `#`). The shortcode supports the following named arguments:
-    "href"          Required reference to either an external link (if it starts with http), a named link (if it can be
-                    found in params.links), or internal reference. External and internal references may include an
-                    anchor "#".
-    "name"          Alias of href.
-    "url"           Alias of href.
-    "cue"           Optional flag to indicate if an external link should show a visual cue, defaults to setting
-                    "main.externalLinks.cue" in the site's parameters.
-    "tab"           Optional flag to indicate if an external link should open in a new tab, defaults to setting
-                    "main.externalLinks.tab" in the site's parameters.
-    "case"          Optional flag to indicate if the retrieved title (e.g. no inner text is provided) of an internal
-                    link should use its original case, defaults to true. If false, the title is set to lower case.
-    "class"         Optional class attribute of the anchor element.
+    Copyright © 2023 The Hinode Team / Mark Dumay. All rights reserved.
+    Use of this source code is governed by The MIT License (MIT) that can be found in the LICENSE file.
+    Visit gethinode.com/license for more details.
 -->
 
-{{- $error := false -}}
+{{ $error := false -}}
+
+<!-- Validate arguments -->
+{{ if partial "utilities/IsInvalidArgs.html" (dict "structure" "link" "args" .Params "group" "shortcode") }}
+    {{ errorf "Invalid arguments: %s" .Position -}}
+    {{ $error = true }}
+{{ end }}
+
+<!-- Initialize arguments -->
 {{ $href := "" }}
 {{ $name := "" }}
 {{ $url := "" }}
@@ -84,6 +78,7 @@
     {{ $url = printf "%s#%s" $url .}}
 {{ end }}
 
+<!-- Main code -->
 {{- if not $error -}}
-    {{ partial "utilities/link.html" (dict "destination" $url "text" $text "cue" $cue "tab" $tab "case" $case "class" $class "page" .Page) }}
+    {{ partial "assets/link.html" (dict "destination" $url "text" $text "cue" $cue "tab" $tab "case" $case "class" $class "page" .Page) }}
 {{- end -}}