safeURL.md (2585B)
1 ---
2 title: safeURL
3 description: Declares the provided string as a safe URL or URL substring.
4 date: 2017-02-01
5 publishdate: 2017-02-01
6 lastmod: 2017-02-01
7 keywords: [strings,urls]
8 categories: [functions]
9 menu:
10 docs:
11 parent: "functions"
12 signature: ["safeURL INPUT"]
13 workson: []
14 hugoversion:
15 relatedfuncs: []
16 deprecated: false
17 aliases: []
18 ---
19
20 `safeURL` declares the provided string as a "safe" URL or URL substring (see [RFC 3986][]). A URL like `javascript:checkThatFormNotEditedBeforeLeavingPage()` from a trusted source should go in the page, but by default dynamic `javascript:` URLs are filtered out since they are a frequently exploited injection vector.
21
22 Without `safeURL`, only the URI schemes `http:`, `https:` and `mailto:` are considered safe by Go templates. If any other URI schemes (e.g., `irc:` and `javascript:`) are detected, the whole URL will be replaced with `#ZgotmplZ`. This is to "defang" any potential attack in the URL by rendering it useless.
23
24 The following examples use a [site `config.toml`][configuration] with the following [menu entry][menus]:
25
26 {{< code file="config.toml" copy="false" >}}
27 [[menu.main]]
28 name = "IRC: #golang at freenode"
29 url = "irc://irc.freenode.net/#golang"
30 {{< /code >}}
31
32 The following is an example of a sidebar partial that may be used in conjunction with the preceding front matter example:
33
34 {{< code file="layouts/partials/bad-url-sidebar-menu.html" copy="false" >}}
35 <!-- This unordered list may be part of a sidebar menu -->
36 <ul>
37 {{ range .Site.Menus.main }}
38 <li><a href="{{ .URL }}">{{ .Name }}</a></li>
39 {{ end }}
40 </ul>
41 {{< /code >}}
42
43 This partial would produce the following HTML output:
44
45 {{< output file="bad-url-sidebar-menu-output.html" >}}
46 <!-- This unordered list may be part of a sidebar menu -->
47 <ul>
48 <li><a href="#ZgotmplZ">IRC: #golang at freenode</a></li>
49 </ul>
50 {{< /output >}}
51
52 The odd output can be remedied by adding ` | safeURL` to our `.URL` page variable:
53
54 {{< code file="layouts/partials/correct-url-sidebar-menu.html" copy="false" >}}
55 <!-- This unordered list may be part of a sidebar menu -->
56 <ul>
57 <li><a href="{{ .URL | safeURL }}">{{ .Name }}</a></li>
58 </ul>
59 {{< /code >}}
60
61 With the `.URL` page variable piped through `safeURL`, we get the desired output:
62
63 {{< output file="correct-url-sidebar-menu-output.html" >}}
64 <ul class="sidebar-menu">
65 <li><a href="irc://irc.freenode.net/#golang">IRC: #golang at freenode</a></li>
66 </ul>
67 {{< /output >}}
68
69 [configuration]: /getting-started/configuration/
70 [menus]: /content-management/menus/
71 [RFC 3986]: https://tools.ietf.org/html/rfc3986