Skip t' th' main rrreadin'

Button

Th' button shortcode displays a click'ble button wit' adjustable color, title an' ay'con.

Go Cap'n Hugo Download Magic

Usage

​
{{% button href="https://gohugo.io/" %}}Go Cap'n Hugo{{% /button %}}
{{% button href="images/magic.gif?download" ay'con="hand-sparkles" style="tip" %}}Download Magic{{% /button %}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "content" "Go Hugo"
  "href" "https://gohugo.io/"
)}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "content" "Download Magic"
  "href" "images/magic.gif?download"
  "icon" "hand-sparkles"
  "style" "tip"
)}}

Parameters

Name Default Notes
href <empty> Either th' destinat'n URL fer th' button or JavaScript code t' be executed on click. If this parameter be not set, th' button will do noth'n but be still displayed as click'ble.

- if start'n wit' javascript: all follow'n text will be executed 'n yer browser
- every other str'n will be interpreted as URL, ye can use link effects as well.
action <empty> Name o' an action executed by yer own script on click, without inline JavaScript. Use this instead o' a JavaScript href if yer ship uses a strict Rrrambl'n Security Policy. See example.
type see notes Th' button type if href be JavaScript or action be set. Otherwise th' parameter be not used. If th' parameter be not given it defaults t' button.
istoggle false When true, th' button announces t' assistive technology that it shows an' hides someth'n. It starts as hidden an' th' theme changes th' state wit' each click. Only used if href be JavaScript or action be set. See example.
borderless false When true, no border will be shown around th' button.
hint <empty> Tooltip fer th' button.
style transparent Th' style scheme used fer th' button.

- by severity: caution, important, info, note, tip, warning
- by brand color: primary, secondary, accent
- by color: blue, cyan, green, grey, magenta, orange, red
- by special color: default, transparent, code, link, action, inline

Ye can also define yer own styles.
color see notes Th' CSS color value t' be used. If not set, th' chosen color depends on th' style. Any given value will overwrite th' default.

- fer severity styles: a nice match'n color fer th' severity
- fer all other styles: th' correspond'n color
ay'con see notes Font Awesome ay'con name set t' th' left o' th' title. Depend'n on th' style there may be a default ay'con. Any given value will overwrite th' default.

- fer severity styles: a nice match'n ay'con fer th' severity
- fer all other styles: <empty>

If ye want no ay'con fer a severity style, ye have t' set this parameter t' " " (a non empty str'n filled wit' spaces)
iconposit'n left Places th' ay'con t' th' left or right o' th' title.
<content> see notes Arbitrary text fer th' button title. Depend'n on th' style there may be a default title. Any given value will overwrite th' default.

- fer severity styles: th' match'n title fer th' severity
- fer all other styles: <empty>

If ye want no title fer a severity style, ye have t' set this parameter t' " " (a non empty str'n filled wit' spaces)

Examples

Style

By Severity

​
{{% button href="https://gohugo.io/" style="caution" %}}Get Cap'n Hugo{{% /button %}}
{{% button href="https://gohugo.io/" style="important" %}}Get Cap'n Hugo{{% /button %}}
{{% button href="https://gohugo.io/" style="info" %}}Get Cap'n Hugo{{% /button %}}
{{% button href="https://gohugo.io/" style="note" %}}Get Cap'n Hugo{{% /button %}}
{{% button href="https://gohugo.io/" style="tip" %}}Get Cap'n Hugo{{% /button %}}
{{% button href="https://gohugo.io/" style="warning" %}}Get Cap'n Hugo{{% /button %}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "content" "Get Hugo"
  "href" "https://gohugo.io/"
  "style" "caution"
)}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "content" "Get Hugo"
  "href" "https://gohugo.io/"
  "style" "important"
)}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "content" "Get Hugo"
  "href" "https://gohugo.io/"
  "style" "info"
)}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "content" "Get Hugo"
  "href" "https://gohugo.io/"
  "style" "note"
)}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "content" "Get Hugo"
  "href" "https://gohugo.io/"
  "style" "tip"
)}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "content" "Get Hugo"
  "href" "https://gohugo.io/"
  "style" "warning"
)}}
Get Cap'n Hugo Get Cap'n Hugo Get Cap'n Hugo Get Cap'n Hugo Get Cap'n Hugo Get Cap'n Hugo

By Brand Colors

​
{{% button href="https://gohugo.io/" style="primary" %}}Get Cap'n Hugo{{% /button %}}
{{% button href="https://gohugo.io/" style="secondary" %}}Get Cap'n Hugo{{% /button %}}
{{% button href="https://gohugo.io/" style="accent" %}}Get Cap'n Hugo{{% /button %}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "content" "Get Hugo"
  "href" "https://gohugo.io/"
  "style" "primary"
)}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "content" "Get Hugo"
  "href" "https://gohugo.io/"
  "style" "secondary"
)}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "content" "Get Hugo"
  "href" "https://gohugo.io/"
  "style" "accent"
)}}
Get Cap'n Hugo Get Cap'n Hugo Get Cap'n Hugo

By Color

​
{{% button href="https://gohugo.io/" style="blue" %}}Get Cap'n Hugo{{% /button %}}
{{% button href="https://gohugo.io/" style="cyan" %}}Get Cap'n Hugo{{% /button %}}
{{% button href="https://gohugo.io/" style="green" %}}Get Cap'n Hugo{{% /button %}}
{{% button href="https://gohugo.io/" style="grey" %}}Get Cap'n Hugo{{% /button %}}
{{% button href="https://gohugo.io/" style="magenta" %}}Get Cap'n Hugo{{% /button %}}
{{% button href="https://gohugo.io/" style="orange" %}}Get Cap'n Hugo{{% /button %}}
{{% button href="https://gohugo.io/" style="red" %}}Get Cap'n Hugo{{% /button %}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "content" "Get Hugo"
  "href" "https://gohugo.io/"
  "style" "blue"
)}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "content" "Get Hugo"
  "href" "https://gohugo.io/"
  "style" "cyan"
)}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "content" "Get Hugo"
  "href" "https://gohugo.io/"
  "style" "green"
)}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "content" "Get Hugo"
  "href" "https://gohugo.io/"
  "style" "grey"
)}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "content" "Get Hugo"
  "href" "https://gohugo.io/"
  "style" "magenta"
)}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "content" "Get Hugo"
  "href" "https://gohugo.io/"
  "style" "orange"
)}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "content" "Get Hugo"
  "href" "https://gohugo.io/"
  "style" "red"
)}}
Get Cap'n Hugo Get Cap'n Hugo Get Cap'n Hugo Get Cap'n Hugo Get Cap'n Hugo Get Cap'n Hugo Get Cap'n Hugo

By Special Color

​
{{% button href="https://gohugo.io/" style="default" %}}Open Link{{% /button %}}
{{% button href="https://gohugo.io/" style="transparent" %}}Open Link{{% /button %}}
{{% button href="https://gohugo.io/" style="code" %}}Open Link{{% /button %}}
{{% button href="https://gohugo.io/" style="link" %}}Open Link{{% /button %}}
{{% button href="https://gohugo.io/" style="action" %}}Open Link{{% /button %}}
{{% button href="https://gohugo.io/" style="inline" %}}Open Link{{% /button %}}

{{% button href="javascript:alert('Some JavaScript')" style="default" %}}Run JavaScript{{% /button %}}
{{% button href="javascript:alert('Some JavaScript')" style="transparent" %}}Run JavaScript{{% /button %}}
{{% button href="javascript:alert('Some JavaScript')" style="code" %}}Run JavaScript{{% /button %}}
{{% button href="javascript:alert('Some JavaScript')" style="link" %}}Run JavaScript{{% /button %}}
{{% button href="javascript:alert('Some JavaScript')" style="action" %}}Run JavaScript{{% /button %}}
{{% button href="javascript:alert('Some JavaScript')" style="inline" %}}Run JavaScript{{% /button %}}

{{% button style="default" %}}Fake Button{{% /button %}}
{{% button style="transparent" %}}Fake Button{{% /button %}}
{{% button style="code" %}}Fake Button{{% /button %}}
{{% button style="link" %}}Fake Button{{% /button %}}
{{% button style="action" %}}Fake Button{{% /button %}}
{{% button style="inline" %}}Fake Button{{% /button %}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "content" "Open Link"
  "href" "https://gohugo.io/"
  "style" "default"
)}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "content" "Open Link"
  "href" "https://gohugo.io/"
  "style" "transparent"
)}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "content" "Open Link"
  "href" "https://gohugo.io/"
  "style" "code"
)}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "content" "Open Link"
  "href" "https://gohugo.io/"
  "style" "link"
)}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "content" "Open Link"
  "href" "https://gohugo.io/"
  "style" "action"
)}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "content" "Open Link"
  "href" "https://gohugo.io/"
  "style" "inline"
)}}

{{ partial "shortcodes/button.html" (dict
  "page" .
  "content" "Run JavaScript"
  "href" "javascript:alert('Some JavaScript')"
  "style" "default"
)}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "content" "Run JavaScript"
  "href" "javascript:alert('Some JavaScript')"
  "style" "transparent"
)}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "content" "Run JavaScript"
  "href" "javascript:alert('Some JavaScript')"
  "style" "code"
)}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "content" "Run JavaScript"
  "href" "javascript:alert('Some JavaScript')"
  "style" "link"
)}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "content" "Run JavaScript"
  "href" "javascript:alert('Some JavaScript')"
  "style" "action"
)}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "content" "Run JavaScript"
  "href" "javascript:alert('Some JavaScript')"
  "style" "inline"
)}}

{{ partial "shortcodes/button.html" (dict
  "page" .
  "content" "Fake Button"
  "style" "default"
)}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "content" "Fake Button"
  "style" "transparent"
)}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "content" "Fake Button"
  "style" "code"
)}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "content" "Fake Button"
  "style" "link"
)}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "content" "Fake Button"
  "style" "action"
)}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "content" "Fake Button"
  "style" "inline"
)}}

Open Link Open Link Open Link Open Link Open Link Open Link

Fake Button Fake Button Fake Button Fake Button Fake Button Fake Button

Ay'con

Empty

​
{{% button hint="Go Hugo" href="https://gohugo.io/" ay'con=" " %}}{{% /button %}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "content" ""
  "hint" "Go Hugo"
  "href" "https://gohugo.io/"
  "icon" " "
)}}

Only wit' Hint

Mouse-over th' button t' see th' hint.

​
{{% button hint="Go t' Hugo's homepage" href="https://gohugo.io/" ay'con="download" %}}{{% /button %}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "content" ""
  "hint" "Go t' Hugo's homepage"
  "href" "https://gohugo.io/"
  "icon" "download"
)}}

T' th' Left

​
{{% button href="https://gohugo.io/" ay'con="download" %}}Get Cap'n Hugo{{% /button %}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "content" "Get Hugo"
  "href" "https://gohugo.io/"
  "icon" "download"
)}}
Get Cap'n Hugo

T' th' Right

​
{{% button href="https://gohugo.io/" ay'con="download" iconposit'n="right" %}}Get Cap'n Hugo{{% /button %}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "content" "Get Hugo"
  "href" "https://gohugo.io/"
  "icon" "download"
  "iconposition" "right"
)}}
Get Cap'n Hugo

Override fer Severity

​
{{% button href="https://gohugo.io/" ay'con="dragon" style="warning" %}}Get Cap'n Hugo{{% /button %}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "content" "Get Hugo"
  "href" "https://gohugo.io/"
  "icon" "dragon"
  "style" "warning"
)}}
Get Cap'n Hugo

Ye can use link effects wit' yer href t' open th' link 'n a different tab or start'n a download.

​
{{% button href="https://gohugo.io/?target=_blank" %}}Go Cap'n Hugo{{% /button %}}
{{% button href="images/magic.gif?download" ay'con="hand-sparkles" style="tip" %}}Download Magic{{% /button %}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "content" "Go Hugo"
  "href" "https://gohugo.io/?target=_blank"
)}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "content" "Download Magic"
  "href" "images/magic.gif?download"
  "icon" "hand-sparkles"
  "style" "tip"
)}}
Go Cap'n Hugo Download Magic

Other

Borderless

​
{{% button borderless="true" href="https://gohugo.io/" style="primary" %}}Get Cap'n Hugo{{% /button %}}
{{% button borderless="true" href="https://gohugo.io/" style="default" %}}Get Cap'n Hugo{{% /button %}}
{{% button borderless="true" href="https://gohugo.io/" style="transparent" %}}Get Cap'n Hugo{{% /button %}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "borderless" "true"
  "content" "Get Hugo"
  "href" "https://gohugo.io/"
  "style" "primary"
)}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "borderless" "true"
  "content" "Get Hugo"
  "href" "https://gohugo.io/"
  "style" "default"
)}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "borderless" "true"
  "content" "Get Hugo"
  "href" "https://gohugo.io/"
  "style" "transparent"
)}}
Get Cap'n Hugo Get Cap'n Hugo Get Cap'n Hugo

Wit' User-Defined Color, Font Awesome Brand Ay'con an' Marrrkdown Title

​
{{% button color="fuchsia" href="https://gohugo.io/" ay'con="fa-fw fab fa-hackerrank" %}}Get **Cap'n Hugo**{{% /button %}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "color" "fuchsia"
  "content" "Get **Hugo**"
  "href" "https://gohugo.io/"
  "icon" "fa-fw fab fa-hackerrank"
)}}
Get Cap'n Hugo

Severity Style wit' All Defaults

​
{{% button href="https://gohugo.io/" style="tip" %}}{{% /button %}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "content" ""
  "href" "https://gohugo.io/"
  "style" "tip"
)}}
Smarrrt Arrrse

Button t' Internal Plank

​
{{% button href="/index.html" %}}Home{{% /button %}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "content" "Home"
  "href" "/index.html"
)}}
Home

Button wit' JavaScript Act'n

If yer JavaScript action does not change th' focus afterwards, make sure t' call this.blur() 'n th' end t' unselect th' button.

​
{{% button href="javascript:alert('Hello world!');this.blur();" ay'con="bullhorn" style="primary" %}}Shout it out{{% /button %}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "content" "Shout it out"
  "href" "javascript:alert('Hello world!');this.blur();"
  "icon" "bullhorn"
  "style" "primary"
)}}

Button wit' Own Act'n

Th' button be written wit' a data-button-action attribute. Handle it 'n yer assets/js/custom.js, which th' theme loads on every plank.

​
{{% button action="shout" ay'con="bullhorn" style="primary" %}}Shout it out{{% /button %}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "action" "shout"
  "content" "Shout it out"
  "icon" "bullhorn"
  "style" "primary"
)}}
​
document.addEventListener('click', funct'n (event) {
  var button = event.target.closest('button[data-button-action="shout"]');
  if (button) {
    alert('Hello world!');
    button.blur();
  }
});

Toggle Button

If yer button shows an' hides someth'n, set istoggle. Th' button be written wit' an aria-expanded attribute tell'n assistive technology whether th' th'n be shown, an' th' theme flips it wit' each click.

​
{{% button action="details" ay'con="eye" istoggle="true" %}}Details{{% /button %}}
{{ partial "shortcodes/button.html" (dict
  "page" .
  "action" "details"
  "content" "Details"
  "icon" "eye"
  "istoggle" "true"
)}}

Yer script reads th' attribute t' know what t' do. Th' theme has flipped it by th' time yer listener runs, so it already tells th' new state.

​
document.addEventListener('click', funct'n (event) {
  var button = event.target.closest('button[data-button-action="details"]');
  if (button) {
    var show = button.getAttribute('aria-expanded') == 'true';
    document.querySelector('#my-details').hidden = !show;
  }
});

If what ye show can also be hidden by other means than th' button, yer script has t' set th' attribute itself 'n that case.

Button within a form Element

T' use native HTML elements 'n yer Marrrkdown, add this 'n yer hugo.toml

hugo.
[marrrkup]
  [marrrkup.goldmark]
    [marrrkup.goldmark.renderer]
      unsafe = true
marrrkup:
  goldmark:
    renderer:
      unsafe: true
{
   "markup": {
      "goldmark": {
         "renderer": {
            "unsafe": true
         }
      }
   }
}
<form action="../../search/index.html" method="get">
  <input name="search-by" class="search-by" type="search">
  {{% button type="submit" style="secondary" icon="search" %}}Search{{% /button %}}
</form>