`link` Shortcode

Bissetii now has a proper shortcode to manage multi-language, relative BaseURL link instead of the conventional Markdown. This way, it's easier to remember one shortcode than multiple ones over the place and easily manage the link across multiple outputs.

By default, Hugo is not able to process irregular BaseURL such as https://zoralab.gitlab.io/bissetii. In fact, it only recognizes https://zoralab.gitlab.io its base URL. This is not feasible for websites hosted on Git version control platforms such as Github Pages and GitLab Pages as project-level pages. Therefore, the need for an independent link shortcode is required.

Also, when using link shortcode in multiple outputs with non-base relative URL (e.g. some/path), it will process and point the link towards its designated output (e.g. AMP will have index.amp.html in the end if no file is specified).

This shortcode is available starting from v1.12.0.

NON-BACKWARD COMPATIBILITY NOTICE

Starting from version v1.13.0, this shortcode uses many Hugo’s urls.Parse function, which in turns using Go’s net/url Package to process all the URLs. The reason is to ensure this shortcode is RFC3986 compliant.

While the parameters are not affected, the data for them are. Please ensure your full documentations migrations before commiting!

Another notable security changes is that one will no longer be able to supply user info embedded URL such as this example: https://username:[email protected]. Doing so will raise as fatal error instead.

The reason to ban embedded URL in this shortcode mainly because Hugo is a static site generator, not a web application. Hence, there is no reason for anyone to hard-code sensitive information like password into your web artifact.

Heads-Up

While the shortcode is useful, it breaks the Markdown syntax conventions due to Hugo specific shortcode feature. Therefore, when using other Markdown renderer, these shortcodes would be rendered as text instead of HTML code fragments.

Be careful and stay safe while using this shortcode. It allows any form of HTML to be embedded into your Markdown page.

Using `link`

There are serveral ways to use link shortcode.

URL-Only Construction

link is capable of constructing the canonical, multi-lingual URL-only output. This is useful when you just want to use the URL for inserting into linking area.

Important Note

Starting from version v1.13.0, you need to apply self-closure for every stand-alone shortcode calls. Here is an example:

1
2
3
{{% link "mylink" "this" "url-only" %}}
		⥥
{{% link "mylink" "this" "url-only" /%}}

Notice the tailing / slash at the end.

To use URL-only construction, you can do the following pattern:

1
{{< link <URL> <LANG> "url-only" />}}

The 1st parameter (<URL>) is the URL you want to construct. It accepts both absolute and relative URL.
The 2nd parameter is the language prefix selection (<LANG>). This is only used for relative URL conversion. To ensure dynamic processing, you can supply "this" as value to use current URL’s language prefix.
The 3rd parameter MUST be hard-coded into "url-only" as value.

Let’s look at the following examples:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
# Supplying Absolute Value
{{< link "https://www.example.com" "" "url-only" />}}
		⥥
https://www.example.com

# Supplying Absolute Value with language prefix
{{< link "https://www.example.com" "this" "url-only" />}}
		⥥
https://www.example.com

# Relative to Base URL (e.g. to access static files)
{{< link "/img/logo.png" "" "url-only" />}}
		⥥
https://bissetii.zoralab.com/img/logo.png

# Relative to Base URL with language Prefix as "zh-hans"
{{< link "/img/logo.png" "zh-hans" "url-only" />}}
		⥥
https://bissetii.zoralab.com/zh-hans/img/logo.png

# Path/Directory relative to Base URL
{{< link "/img/" "" "url-only" />}}
		⥥
https://bissetii.zoralab.com/img/

# Path/Directory (no tail) relative to Base URL
{{< link "/img" "" "url-only" />}}
		⥥
https://bissetii.zoralab.com/img/

# Path/Directory relative to Base URL with "this" language prefix
{{< link "/img/" "this" "url-only" />}}
		⥥
https://bissetii.zoralab.com/en/img/

# Path/Directory (no tail) relative to Base URL with "this" language prefix
{{< link "/img" "this" "url-only" />}}
		⥥
https://bissetii.zoralab.com/en/img/

# Path/Directory relative to Base URL with "zh-hans" language prefix
{{< link "/img/" "zh-hans" "url-only" />}}
		⥥
https://bissetii.zoralab.com/zh-hans/img/

# Path/Directory (no tail) relative to Base URL with  "zh-hans" language prefix
{{< link "/img" "zh-hans" "url-only" />}}
		⥥
https://bissetii.zoralab.com/zh-hans/img/

# Relative to current URL (without leading "/" slash)
{{< link "img/logo.png" "" "url-only" />}}
		⥥
https://bissetii.zoralab.com/en/shortcodes/link/img/logo.png

# Relative to current URL with language prefix overwrite to "zh-hans"
{{< link "img/logo.png" "zh-hans" "url-only" />}}
		⥥
https://bissetii.zoralab.com/zh-hans/shortcodes/link/img/logo.png

# Relative to current URL using the current language prefix `this`
{{< link "img/logo.png" "this" "url-only" />}}
		⥥
https://bissetii.zoralab.com/en/shortcodes/link/img/logo.png

# Path/Directory relative to current URL
{{< link "img/" "" "url-only" />}}
		⥥
https://bissetii.zoralab.com/en/shortcodes/link/img/

# Path/Directory (no tail) relative to current URL
{{< link "img" "" "url-only" />}}
		⥥
https://bissetii.zoralab.com/en/shortcodes/link/img/

# Path/Directory relative to current URL with "this" language prefix
{{< link "img/" "this" "url-only" />}}
		⥥
https://bissetii.zoralab.com/en/shortcodes/link/img/

# Path/Directory (no tail) relative to current URL with "this" language prefix
{{< link "img" "this" "url-only" />}}
		⥥
https://bissetii.zoralab.com/en/shortcodes/link/img/

# Path/Directory relative to current URL with "zh-hans" language prefix
{{< link "img/" "zh-hans" "url-only" />}}
		⥥
https://bissetii.zoralab.com/zh-hans/shortcodes/link/img/

# Path/Directory (no tail) relative to current URL with "zh-hans" language prefix
{{< link "img" "zh-hans" "url-only" />}}
		⥥
https://bissetii.zoralab.com/zh-hans/shortcodes/link/img/

TIP

You can also reuse the Markdown link construction format. Example:

1
[My Link]({{< link "/img/logo.png" "" url-only />}})

Produces the following markdown under-the-hood:

1
[My Link](https://bissetii.zoralab.com/img/logo.png)

Closing Tag

For version v1.12.5 and below, close tag is done by supplying the first parameter as hard-coded "close" value as such:

{{< link "close" >}}
	 ⥥
	</a>

HTML Link Tag

link is also primarily used for generating a full-fletch HTML <a> tag. This is the default behavior for generating the HTML <a> tag with any supported attributes.

We will walk through each parameter for creating the HTML link tag.

Link URL

The 1st parameter is the URL itself. Likewise, link accepts both absolute and relative URL with Bissetii’s own BaseURL processing.

This is a compulsory parameter. Here are the usage examples:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
# Absolute link
{{% link "https://www.example.com" /%}}
		⥥
<link href="https://www.example.com"/>


# File relative to base URL
{{% link "/img/logo.png" /%}}
		⥥
<link href="https://bissetii.zoralab.com/img/logo.png"/>


# Path/directory relative to base URL
{{% link "/img" /%}}
		⥥
<link href="https://bissetii.zoralab.com/img/"/>


# File Relative link to current URL
{{% link "img/logo.png" /%}}
		⥥
<link href="https://bissetii.zoralab.com/en/shortcodes/link/img/logo.png"
	hreflang="en"/>


# Path/directory relative to current URL
{{% link "img" /%}}
		⥥
<link href="https://bissetii.zoralab.com/en/shortcodes/link/img/"
	hreflang="en"/>

Language Prefix

The 2nd parameter is the specific language prefix. This is used for Bissetii internal URL processing for relative URLs. When a language is recongized and there is no given overwrite directive (see Overwrite Language Hinting Link Parameter below), this shortcode will automatically fills in hreflang= attribute.

For supporting dynamic processing, this parameter accepts "this" as a value where it uses the current page’s language prefix instead. If the relative URL is relative to base URL while leaving this field as empty string "" will cause the URL relative to BaseURL.

This is a compulsory parameter. Here are the usage examples:

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
# Supplying Absolute Value
{{% link "https://www.example.com" "" /%}}
		⥥
<link href="https://www.example.com"/>


# Supplying Absolute Value with 'this' language prefix
{{% link "https://www.example.com" "this" /%}}
		⥥
<link href="https://www.example.com"/>


# Supplying Absolute Value with 'zh-hans' language prefix
{{% link "https://www.example.com" "zh-hans" /%}}
		⥥
<link href="https://www.example.com"/>


# Relative to Base URL (e.g. to access static files)
{{% link "/img/logo.png" "" /%}}
		⥥
<link href="https://bissetii.zoralab.com/img/logo.png"/>


# Relative to Base URL with language Prefix as "zh-hans"
{{% link "/img/logo.png" "zh-hans" /%}}
		⥥
<link href="https://bissetii.zoralab.com/zh-hans/img/logo.png"
	hreflang="zh-hans"/>


# Path/Directory relative to Base URL
{{% link "/img/" "" /%}}
		⥥
<link href="https://bissetii.zoralab.com/img/"/>


# Path/Directory (no tail) relative to Base URL
{{% link "/img" "" /%}}
		⥥
<link href="https://bissetii.zoralab.com/img/"/>


# Path/Directory relative to Base URL with "this" language prefix
{{% link "/img/" "this" /%}}
		⥥
<link href="https://bissetii.zoralab.com/en/img/"
	hreflang="en"/>


# Path/Directory (no tail) relative to Base URL with "this" language prefix
{{% link "/img" "this" /%}}
		⥥
<link href="https://bissetii.zoralab.com/en/img/"
	hreflang="en"/>


# Path/Directory relative to Base URL with "zh-hans" language prefix
{{% link "/img/" "zh-hans" /%}}
		⥥
<link href="https://bissetii.zoralab.com/zh-hans/img/"
	hreflang="zh-hans"/>


# Path/Directory (no tail) relative to Base URL with  "zh-hans" language prefix
{{% link "/img" "zh-hans" /%}}
		⥥
<link href="https://bissetii.zoralab.com/zh-hans/img/"
	hreflang="zh-hans"/>


# Relative to current URL (without leading "/" slash)
{{% link "img/logo.png" "" /%}}
		⥥
<link href="https://bissetii.zoralab.com/en/shortcodes/link/img/logo.png"
	hreflang="en"/>


# Relative to current URL using the current language prefix `this`
{{% link "img/logo.png" "this" /%}}
		⥥
<link href="https://bissetii.zoralab.com/en/shortcodes/link/img/logo.png"
	hreflang="en"/>


# Relative to current URL with language prefix overwrite to "zh-hans"
{{% link "img/logo.png" "zh-hans" /%}}
		⥥
<link href="https://bissetii.zoralab.com/zh-hans/shortcodes/link/img/logo.png"
	hreflang="zh-hans"/>


# Path/Directory relative to current URL
{{% link "img/" "" /%}}
		⥥
<link href="https://bissetii.zoralab.com/en/shortcodes/link/img/"
	hreflang="en"/>


# Path/Directory (no tail) relative to current URL
{{% link "img" "" /%}}
		⥥
<link href="https://bissetii.zoralab.com/en/shortcodes/link/img/"
	hreflang="en"/>


# Path/Directory relative to current URL with "this" language prefix
{{% link "img/" "this" /%}}
		⥥
<link href="https://bissetii.zoralab.com/en/shortcodes/link/img/"
	hreflang="en"/>


# Path/Directory (no tail) relative to current URL with "this" language prefix
{{% link "img" "this" /%}}
		⥥
<link href="https://bissetii.zoralab.com/en/shortcodes/link/img/"
	hreflang="en"/>


# Path/Directory relative to current URL with "zh-hans" language prefix
{{% link "img/" "zh-hans" /%}}
		⥥
<link href="https://bissetii.zoralab.com/zh-hans/shortcodes/link/img/"
	hreflang="zh-hans"/>


# Path/Directory (no tail) relative to current URL with "zh-hans" language prefix
{{% link "img" "zh-hans" /%}}
		⥥
<link href="https://bissetii.zoralab.com/zh-hans/shortcodes/link/img/"
	hreflang="zh-hans"/>

Relationship

The 3rd parameter is the link relationship. This is useful for specifying link relationship between the current page and the linked page. One can use it to describe links for web crawlers such as nofollow.

This parameter is optional and should be set blank ("") if the following parameters are used.

Here are the usage examples:

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
# Supplying Absolute Value
{{% link "https://www.example.com" "" "nofollow" /%}}
		⥥
<link href="https://www.example.com"
	rel="nofollow"/>


# Supplying Absolute Value with 'this' language prefix
{{% link "https://www.example.com" "this" "nofollow" /%}}
		⥥
<link href="https://www.example.com"
	rel="nofollow"/>


# Supplying Absolute Value with 'zh-hans' language prefix
{{% link "https://www.example.com" "zh-hans" "nofollow" /%}}
		⥥
<link href="https://www.example.com"
	rel="nofollow"/>


# Relative to Base URL (e.g. to access static files)
{{% link "/img/logo.png" "" "nofollow" /%}}
		⥥
<link href="https://bissetii.zoralab.com/img/logo.png"
	rel="nofollow"/>


# Relative to Base URL with language Prefix as "zh-hans"
{{% link "/img/logo.png" "zh-hans" "nofollow" /%}}
		⥥
<link href="https://bissetii.zoralab.com/zh-hans/img/logo.png"
	rel="nofollow"
	hreflang="zh-hans"/>


# Path/Directory relative to Base URL
{{% link "/img/" "" "nofollow" /%}}
		⥥
<link href="https://bissetii.zoralab.com/img/"
	rel="nofollow"/>


# Path/Directory (no tail) relative to Base URL
{{% link "/img" "" "nofollow" /%}}
		⥥
<link href="https://bissetii.zoralab.com/img/"
	rel="nofollow"/>


# Path/Directory relative to Base URL with "this" language prefix
{{% link "/img/" "this" "nofollow" /%}}
		⥥
<link href="https://bissetii.zoralab.com/en/img/"
	rel="nofollow"
	hreflang="en"/>


# Path/Directory (no tail) relative to Base URL with "this" language prefix
{{% link "/img" "this" "nofollow" /%}}
		⥥
<link href="https://bissetii.zoralab.com/en/img/"
	rel="nofollow"
	hreflang="en"/>


# Path/Directory relative to Base URL with "zh-hans" language prefix
{{% link "/img/" "zh-hans" "nofollow" /%}}
		⥥
<link href="https://bissetii.zoralab.com/zh-hans/img/"
	rel="nofollow"
	hreflang="zh-hans"/>


# Path/Directory (no tail) relative to Base URL with  "zh-hans" language prefix
{{% link "/img" "zh-hans" "nofollow" /%}}
		⥥
<link href="https://bissetii.zoralab.com/zh-hans/img/"
	rel="nofollow"
	hreflang="zh-hans"/>


# Relative to current URL (without leading "/" slash)
{{% link "img/logo.png" "" "nofollow" /%}}
		⥥
<link href="https://bissetii.zoralab.com/en/shortcodes/link/img/logo.png"
	rel="nofollow"
	hreflang="en"/>


# Relative to current URL using the current language prefix `this`
{{% link "img/logo.png" "this" "nofollow" /%}}
		⥥
<link href="https://bissetii.zoralab.com/en/shortcodes/link/img/logo.png"
	rel="nofollow"
	hreflang="en"/>


# Relative to current URL with language prefix overwrite to "zh-hans"
{{% link "img/logo.png" "zh-hans" "nofollow" /%}}
		⥥
<link href="https://bissetii.zoralab.com/zh-hans/shortcodes/link/img/logo.png"
	rel="nofollow"
	hreflang="zh-hans"/>


# Path/Directory relative to current URL
{{% link "img/" "" "nofollow" /%}}
		⥥
<link href="https://bissetii.zoralab.com/en/shortcodes/link/img/"
	rel="nofollow"
	hreflang="en"/>


# Path/Directory (no tail) relative to current URL
{{% link "img" "" "nofollow" /%}}
		⥥
<link href="https://bissetii.zoralab.com/en/shortcodes/link/img/"
	rel="nofollow"
	hreflang="en"/>


# Path/Directory relative to current URL with "this" language prefix
{{% link "img/" "this" "nofollow" /%}}
		⥥
<link href="https://bissetii.zoralab.com/en/shortcodes/link/img/"
	rel="nofollow"
	hreflang="en"/>


# Path/Directory (no tail) relative to current URL with "this" language prefix
{{% link "img" "this" "nofollow" /%}}
		⥥
<link href="https://bissetii.zoralab.com/en/shortcodes/link/img/"
	rel="nofollow"
	hreflang="en"/>


# Path/Directory relative to current URL with "zh-hans" language prefix
{{% link "img/" "zh-hans" "nofollow" /%}}
		⥥
<link href="https://bissetii.zoralab.com/zh-hans/shortcodes/link/img/"
	rel="nofollow"
	hreflang="zh-hans"/>


# Path/Directory (no tail) relative to current URL with "zh-hans" language prefix
{{% link "img" "zh-hans" "nofollow" /%}}
		⥥
<link href="https://bissetii.zoralab.com/zh-hans/shortcodes/link/img/"
	rel="nofollow"
	hreflang="zh-hans"/>

Target Action

The 4th parameter is the link target action. This is useful for specifying the link action upon clicked like opening the linked page in a new tab or windows.