mirror of https://github.com/gohugoio/hugo
318 lines
12 KiB
HTML
318 lines
12 KiB
HTML
{{- /* Last modified: 2025-01-19T14:44:56-08:00 */}}
|
|
|
|
{{- /*
|
|
Copyright 2025 Veriphor LLC
|
|
|
|
Licensed under the Apache License, Version 2.0 (the "License"); you may not
|
|
use this file except in compliance with the License. You may obtain a copy of
|
|
the License at
|
|
|
|
https://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
|
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
|
License for the specific language governing permissions and limitations under
|
|
the License.
|
|
*/}}
|
|
|
|
{{- /*
|
|
This render hook resolves internal destinations by looking for a matching:
|
|
|
|
1. Content page
|
|
2. Page resource (a file in the current page bundle)
|
|
3. Section resource (a file in the current section)
|
|
4. Global resource (a file in the assets directory)
|
|
|
|
It skips the section resource lookup if the current page is a leaf bundle.
|
|
|
|
External destinations are not modified.
|
|
|
|
You must place global resources in the assets directory. If you have placed
|
|
your resources in the static directory, and you are unable or unwilling to move
|
|
them, you must mount the static directory to the assets directory by including
|
|
both of these entries in your site configuration:
|
|
|
|
[[module.mounts]]
|
|
source = 'assets'
|
|
target = 'assets'
|
|
|
|
[[module.mounts]]
|
|
source = 'static'
|
|
target = 'assets'
|
|
|
|
By default, if this render hook is unable to resolve a destination, including a
|
|
fragment if present, it passes the destination through without modification. To
|
|
emit a warning or error, set the error level in your site configuration:
|
|
|
|
[params.render_hooks.link]
|
|
errorLevel = 'warning' # ignore (default), warning, or error (fails the build)
|
|
|
|
When you set the error level to warning, and you are in a development
|
|
environment, you can visually highlight broken internal links:
|
|
|
|
[params.render_hooks.link]
|
|
errorLevel = 'warning' # ignore (default), warning, or error (fails the build)
|
|
highlightBroken = true # true or false (default)
|
|
|
|
This will add a "broken" class to anchor elements with invalid src attributes.
|
|
Add a rule to your CSS targeting the broken links:
|
|
|
|
a.broken {
|
|
background: #ff0;
|
|
border: 2px solid #f00;
|
|
padding: 0.1em 0.2em;
|
|
}
|
|
|
|
This render hook may be unable to resolve destinations created with the ref and
|
|
relref shortcodes. Unless you set the error level to ignore you should not use
|
|
either of these shortcodes in conjunction with this render hook.
|
|
|
|
@context {string} Destination The link destination.
|
|
@context {page} Page A reference to the page containing the link.
|
|
@context {string} PlainText The link description as plain text.
|
|
@context {string} Text The link description.
|
|
@context {string} Title The link title.
|
|
|
|
@returns {template.html}
|
|
*/}}
|
|
|
|
{{- /* Initialize. */}}
|
|
{{- $renderHookName := "link" }}
|
|
|
|
{{- /* Verify minimum required version. */}}
|
|
{{- $minHugoVersion := "0.141.0" }}
|
|
{{- if lt hugo.Version $minHugoVersion }}
|
|
{{- errorf "The %q render hook requires Hugo v%s or later." $renderHookName $minHugoVersion }}
|
|
{{- end }}
|
|
|
|
{{- /* Error level when unable to resolve destination: ignore, warning, or error. */}}
|
|
{{- $errorLevel := or site.Params.render_hooks.link.errorLevel "ignore" | lower }}
|
|
|
|
{{- /* If true, adds "broken" class to broken links. Applicable in development environment when errorLevel is warning. */}}
|
|
{{- $highlightBrokenLinks := or site.Params.render_hooks.link.highlightBroken false }}
|
|
|
|
{{- /* Validate error level. */}}
|
|
{{- if not (in (slice "ignore" "warning" "error") $errorLevel) }}
|
|
{{- errorf "The %q render hook is misconfigured. The errorLevel %q is invalid. Please check your site configuration." $renderHookName $errorLevel }}
|
|
{{- end }}
|
|
|
|
{{- /* Determine content path for warning and error messages. */}}
|
|
{{- $contentPath := .Page.String }}
|
|
|
|
{{- /* Parse destination. */}}
|
|
{{- $u := urls.Parse .Destination }}
|
|
|
|
{{- /* Set common message. */}}
|
|
{{- $msg := printf "The %q render hook was unable to resolve the destination %q in %s" $renderHookName $u.String $contentPath }}
|
|
|
|
{{- /* Set attributes for anchor element. */}}
|
|
{{- $attrs := dict "href" $u.String }}
|
|
{{- if eq $u.String "g" }}
|
|
{{- /* Destination is a glossary term. */}}
|
|
{{- $ctx := dict
|
|
"contentPath" $contentPath
|
|
"errorLevel" $errorLevel
|
|
"renderHookName" $renderHookName
|
|
"text" .Text
|
|
}}
|
|
{{- $attrs = partial "inline/h-rh-l/get-glossary-link-attributes.html" $ctx }}
|
|
{{- else if $u.IsAbs }}
|
|
{{- /* Destination is a remote resource. */}}
|
|
{{- $attrs = merge $attrs (dict "rel" "external") }}
|
|
{{- else }}
|
|
{{- with $u.Path }}
|
|
{{- with $p := or ($.PageInner.GetPage .) ($.PageInner.GetPage (strings.TrimRight "/" .)) }}
|
|
{{- /* Destination is a page. */}}
|
|
{{- $href := .RelPermalink }}
|
|
{{- with $u.RawQuery }}
|
|
{{- $href = printf "%s?%s" $href . }}
|
|
{{- end }}
|
|
{{- with $u.Fragment }}
|
|
{{- $ctx := dict
|
|
"contentPath" $contentPath
|
|
"errorLevel" $errorLevel
|
|
"page" $p
|
|
"parsedURL" $u
|
|
"renderHookName" $renderHookName
|
|
}}
|
|
{{- partial "inline/h-rh-l/validate-fragment.html" $ctx }}
|
|
{{- $href = printf "%s#%s" $href . }}
|
|
{{- end }}
|
|
{{- $attrs = dict "href" $href }}
|
|
{{- else with $.PageInner.Resources.Get $u.Path }}
|
|
{{- /* Destination is a page resource; drop query and fragment. */}}
|
|
{{- $attrs = dict "href" .RelPermalink }}
|
|
{{- else with (and (ne $.Page.BundleType "leaf") ($.Page.CurrentSection.Resources.Get $u.Path)) }}
|
|
{{- /* Destination is a section resource, and current page is not a leaf bundle. */}}
|
|
{{- $attrs = dict "href" .RelPermalink }}
|
|
{{- else with resources.Get $u.Path }}
|
|
{{- /* Destination is a global resource; drop query and fragment. */}}
|
|
{{- $attrs = dict "href" .RelPermalink }}
|
|
{{- else }}
|
|
{{- if eq $errorLevel "warning" }}
|
|
{{- warnf $msg }}
|
|
{{- if and $highlightBrokenLinks hugo.IsDevelopment }}
|
|
{{- $attrs = merge $attrs (dict "class" "broken") }}
|
|
{{- end }}
|
|
{{- else if eq $errorLevel "error" }}
|
|
{{- errorf $msg }}
|
|
{{- end }}
|
|
{{- end }}
|
|
{{- else }}
|
|
{{- with $u.Fragment }}
|
|
{{- /* Destination is on the same page; prepend relative permalink. */}}
|
|
{{- $ctx := dict
|
|
"contentPath" $contentPath
|
|
"errorLevel" $errorLevel
|
|
"page" $.Page
|
|
"parsedURL" $u
|
|
"renderHookName" $renderHookName
|
|
}}
|
|
{{- partial "inline/h-rh-l/validate-fragment.html" $ctx }}
|
|
{{- $attrs = dict "href" (printf "%s#%s" $.Page.RelPermalink .) }}
|
|
{{- else }}
|
|
{{- if eq $errorLevel "warning" }}
|
|
{{- warnf $msg }}
|
|
{{- if and $highlightBrokenLinks hugo.IsDevelopment }}
|
|
{{- $attrs = merge $attrs (dict "class" "broken") }}
|
|
{{- end }}
|
|
{{- else if eq $errorLevel "error" }}
|
|
{{- errorf $msg }}
|
|
{{- end }}
|
|
{{- end }}
|
|
{{- end }}
|
|
{{- end }}
|
|
|
|
{{- /* Render anchor element. */ -}}
|
|
<a
|
|
{{- with .Title }} title="{{ . }}" {{- end }}
|
|
{{- range $k, $v := $attrs }}
|
|
{{- if $v }}
|
|
{{- printf " %s=%q" $k ($v | transform.HTMLEscape) | safeHTMLAttr }}
|
|
{{- end }}
|
|
{{- end -}}
|
|
>{{ .Text }}</a>
|
|
|
|
{{- define "partials/inline/h-rh-l/validate-fragment.html" }}
|
|
{{- /*
|
|
Validates the fragment portion of a link destination.
|
|
|
|
@context {string} contentPath The page containing the link.
|
|
@context {string} errorLevel The error level when unable to resolve destination; ignore (default), warning, or error.
|
|
@context {page} page The page corresponding to the link destination
|
|
@context {struct} parsedURL The link destination parsed by urls.Parse.
|
|
@context {string} renderHookName The name of the render hook.
|
|
*/}}
|
|
|
|
{{- /* Initialize. */}}
|
|
{{- $contentPath := .contentPath }}
|
|
{{- $errorLevel := .errorLevel }}
|
|
{{- $p := .page }}
|
|
{{- $u := .parsedURL }}
|
|
{{- $renderHookName := .renderHookName }}
|
|
|
|
{{- /* Validate. */}}
|
|
{{- with $u.Fragment }}
|
|
{{- if $p.Fragments.Identifiers.Contains . }}
|
|
{{- if gt ($p.Fragments.Identifiers.Count .) 1 }}
|
|
{{- $msg := printf "The %q render hook detected duplicate heading IDs %q in %s" $renderHookName . $contentPath }}
|
|
{{- if eq $errorLevel "warning" }}
|
|
{{- warnf $msg }}
|
|
{{- else if eq $errorLevel "error" }}
|
|
{{- errorf $msg }}
|
|
{{- end }}
|
|
{{- end }}
|
|
{{- else }}
|
|
{{- /* Determine target path for warning and error message. */}}
|
|
{{- $targetPath := "" }}
|
|
{{- with $p.File }}
|
|
{{- $targetPath = .Path }}
|
|
{{- else }}
|
|
{{- $targetPath = .Path }}
|
|
{{- end }}
|
|
{{- /* Set common message. */}}
|
|
{{- $msg := printf "The %q render hook was unable to find heading ID %q in %s. See %s" $renderHookName . $targetPath $contentPath }}
|
|
{{- if eq $targetPath $contentPath }}
|
|
{{- $msg = printf "The %q render hook was unable to find heading ID %q in %s" $renderHookName . $targetPath }}
|
|
{{- end }}
|
|
{{- /* Throw warning or error. */}}
|
|
{{- if eq $errorLevel "warning" }}
|
|
{{- warnf $msg }}
|
|
{{- else if eq $errorLevel "error" }}
|
|
{{- errorf $msg }}
|
|
{{- end }}
|
|
{{- end }}
|
|
{{- end }}
|
|
{{- end }}
|
|
|
|
{{- define "partials/inline/h-rh-l/get-glossary-link-attributes.html" }}
|
|
{{- /*
|
|
Returns the anchor element attributes for a link to the given glossary term.
|
|
|
|
It first checks for the existence of a glossary page for the given term. If
|
|
no page is found, it then checks for a glossary page for the singular form of
|
|
the term. If neither page exists it throws a warning or error dependent on
|
|
the errorLevel setting
|
|
|
|
The returned href attribute does not point to the glossary term page.
|
|
Instead, via its fragment, it points to an entry on the glossary page.
|
|
|
|
@context {string} contentPath The page containing the link.
|
|
@context {string} errorLevel The error level when unable to resolve destination; ignore (default), warning, or error.
|
|
@context {string} renderHookName The name of the render hook.
|
|
@context {string} text The link text.
|
|
*/}}
|
|
|
|
{{- /* Get context.. */}}
|
|
{{- $contentPath := .contentPath }}
|
|
{{- $errorLevel := .errorLevel }}
|
|
{{- $renderHookName := .renderHookName }}
|
|
{{- $text := .text | transform.Plainify | strings.ToLower }}
|
|
|
|
{{- /* Initialize. */}}
|
|
{{- $glossaryPath := "/getting-started/glossary" }}
|
|
{{- $termGiven := $text }}
|
|
{{- $termActual := "" }}
|
|
{{- $termSingular := inflect.Singularize $termGiven }}
|
|
|
|
{{- /* Verify that the glossary page exists. */}}
|
|
{{- $glossaryPage := site.GetPage $glossaryPath }}
|
|
{{- if not $glossaryPage }}
|
|
{{- errorf "The %q render hook was unable to find %s: see %s" $renderHookName $glossaryPath $contentPath }}
|
|
{{- end }}
|
|
|
|
{{- /* Theres a better way to handle this, but it works for now. */}}
|
|
{{- $cheating := dict
|
|
"chaining" "chain"
|
|
"localize" "localization"
|
|
"localized" "localization"
|
|
"paginating" "paginate"
|
|
"walking" "walk"
|
|
}}
|
|
|
|
{{- /* Verify that a glossary term page exists for the given term. */}}
|
|
{{- if site.GetPage (urls.JoinPath $glossaryPath ($termGiven | urlize)) }}
|
|
{{- $termActual = $termGiven }}
|
|
{{- else if site.GetPage (urls.JoinPath $glossaryPath ($termSingular | urlize)) }}
|
|
{{- $termActual = $termSingular }}
|
|
{{- else }}
|
|
{{- $termToTest := index $cheating $termGiven }}
|
|
{{- if site.GetPage (urls.JoinPath $glossaryPath ($termToTest | urlize)) }}
|
|
{{- $termActual = $termToTest }}
|
|
{{- end }}
|
|
{{- end }}
|
|
|
|
{{- if not $termActual }}
|
|
{{- errorf "The %q render hook was unable to find a glossary page for either the singular or plural form of the term %q: see %s" $renderHookName $termGiven $contentPath }}
|
|
{{- end }}
|
|
|
|
{{- /* Create the href attribute. */}}
|
|
{{- $href := ""}}
|
|
{{- if $termActual }}
|
|
{{- $href = fmt.Printf "%s#%s" $glossaryPage.RelPermalink (anchorize $termActual) }}
|
|
{{- end }}
|
|
|
|
{{- return (dict "href" $href) }}
|
|
{{- end -}}
|