github.com/jbramsden/hugo@v0.47.1/docs/content/en/functions/safeURL.md (about)

     1  ---
     2  title: safeURL
     3  description: Declares the provided string as a safe URL or URL substring.
     4  godocref: https://golang.org/pkg/html/template/#HTMLEscape
     5  date: 2017-02-01
     6  publishdate: 2017-02-01
     7  lastmod: 2017-02-01
     8  keywords: [strings,urls]
     9  categories: [functions]
    10  menu:
    11    docs:
    12      parent: "functions"
    13  signature: ["safeURL INPUT"]
    14  workson: []
    15  hugoversion:
    16  relatedfuncs: []
    17  deprecated: false
    18  aliases: []
    19  ---
    20  
    21  `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.
    22  
    23  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.
    24  
    25  The following examples use a [site `config.toml`][configuration] with the following [menu entry][menus]:
    26  
    27  {{< code file="config.toml" copy="false" >}}
    28  [[menu.main]]
    29      name = "IRC: #golang at freenode"
    30      url = "irc://irc.freenode.net/#golang"
    31  {{< /code >}}
    32  
    33  The following is an example of a sidebar partial that may be used in conjunction with the preceding front matter example:
    34  
    35  {{< code file="layouts/partials/bad-url-sidebar-menu.html" copy="false" >}}
    36  <!-- This unordered list may be part of a sidebar menu -->
    37  <ul>
    38    {{ range .Site.Menus.main }}
    39    <li><a href="{{ .URL }}">{{ .Name }}</a></li>
    40    {{ end }}
    41  </ul>
    42  {{< /code >}}
    43  
    44  This partial would produce the following HTML output:
    45  
    46  {{< output file="bad-url-sidebar-menu-output.html" >}}
    47  <!-- This unordered list may be part of a sidebar menu -->
    48  <ul>
    49      <li><a href="#ZgotmplZ">IRC: #golang at freenode</a></li>
    50  </ul>
    51  {{< /output >}}
    52  
    53  The odd output can be remedied by adding ` | safeURL` to our `.Title` page variable:
    54  
    55  {{< code file="layouts/partials/correct-url-sidebar-menu.html" copy="false" >}}
    56  <!-- This unordered list may be part of a sidebar menu -->
    57  <ul>
    58      <li><a href="{{ .URL | safeURL }}">{{ .Name }}</a></li>
    59  </ul>
    60  {{< /code >}}
    61  
    62  With the `.URL` page variable piped through `safeURL`, we get the desired output:
    63  
    64  {{< output file="correct-url-sidebar-menu-output.html" >}}
    65  <ul class="sidebar-menu">
    66      <li><a href="irc://irc.freenode.net/#golang">IRC: #golang at freenode</a></li>
    67  </ul>
    68  {{< /output >}}
    69  
    70  [configuration]: /getting-started/configuration/
    71  [menus]: /content-management/menus/
    72  [RFC 3986]: http://tools.ietf.org/html/rfc3986