Hugo Expand shortcode

Hugo Expand shortcode

September 2020  765  4 mins Hugo

A shortcode which allows one provide information which is hidden by default, if desired the user may expand it. This is useful to provide more detailed information which does not fit in a footnote or optional sections within the content. Readers which are interested may consume the extra content while other readers are not bothered by it.

This article was written for Hugo 0.74.

Usage

Add the hidden content in the expand shortcode and you’re done. By default the expander will be collapsed. Note this shortcode requires to use the %-syntax (see this post for more info).

option   effect   optionaldefault
0sets the title of the expanderyesExpand
1sets the expand iconyes↕

When starting with a heading the first content line must be blank; this can be considered a bug in Hugo. Also a blank line in markdown after the shortcode is required.

Example

{{% expand "Expand example" %}}

#### Example

Add any mark-up, shortcode or footnotes here
{{% /expand %}}

Example

Add any mark-up, shortcode or footnotes here

Code

The current CSS reserves the full space of the div even when not expanded. Hence you will have a lot of unwanted blank space at the end of the page. If you know how to resolve this please contact me.

The shortcode is fairly straight forward but looks more complicated due to the printf usage. For more info why print is required see this post.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

{{ $text := (.Get 0) | markdownify | default "Expand" }}
{{ $icon := (.Get 1) | default "↕" }}
{{ $id :=  index (seq 1000 | shuffle) 0 }}
{{ $headingId := $text | anchorize }}
{{ $collapseIcon := partial "inline-svg" "chevron-up" }}
{{ printf "<div id=\"%s\" class=\"md-expand\">" $headingId | htmlUnescape | safeHTML }}
{{ printf "<label for=\"expander-%d\">" $id | htmlUnescape | safeHTML }}
{{ printf "<div class=\"md-expand-head\">" | htmlUnescape | safeHTML }}
{{ printf "<span>%s</span>" $text | htmlUnescape | safeHTML }}
{{ printf "<span>%s</span>" $icon | htmlUnescape | safeHTML }}
{{ printf "</div>" | htmlUnescape | safeHTML }}
{{ printf "</label>" | htmlUnescape | safeHTML }}
{{ printf "<input id=\"expander-%d\" type=\"checkbox\" class=\"hidden\" />" $id | htmlUnescape | safeHTML }}
{{ printf "<div class=\"md-expand-content markdown-inner\">" | htmlUnescape | safeHTML }}
{{ printf "<div class=\"md-content\">" | htmlUnescape | safeHTML }}
{{ .Inner | safeHTML }}
{{ printf "</div>" | htmlUnescape | safeHTML }}
{{ printf "<label for=\"expander-%d\" class=\"tag md-collapse tooltipped tooltipped-w\" aria-label=\"Collapse '%s'\">%s</label>" $id $text $collapseIcon | htmlUnescape | safeHTML }}
{{ printf "</div>" | htmlUnescape | safeHTML }}
{{ printf "<div class=\"md-footer\"></div>" | htmlUnescape | safeHTML }}
{{ printf "</div>" | htmlUnescape | safeHTML }}

In CSS display: none; was explicitly avoided to hide the content because it might break some libraries when used within the expandable content, for example mermaid.

 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

.md-expand {
  margin-top: 1rem;
  margin-bottom: 1rem;

  border: 1px solid var(--md-bg-color-dark);
  border-radius: $border-radius;

  .md-expand-head {
    display: flex;
    justify-content: space-between;
    background: var(--md-bg-color-light);
    padding: 0.5rem 1rem;
    cursor: pointer;
  }

  .md-expand-content {
    display: grid;
    grid-template-columns: auto 2em;
    min-height: 0; // Work around
    min-width: 0; // Work around

    padding: 1rem;
    padding-right: 0;
  }

  .md-content {
    grid-column: 1;
    min-height: 0; // Work around
    min-width: 0; // Work around

    margin-top: -1em;
    margin-bottom: -1em;
    padding-right: 0;
  }

  .md-collapse {
    position: -webkit-sticky;
    position: sticky;

    grid-column: 2;
    align-self: end;

    bottom: 3rem;

    width: 2em;

    cursor: pointer;

    &:hover {
      color: var(--primary-color);
    }
  }

  .md-footer {
    background: var(--md-bg-color-light);
    padding: 0.5rem 1rem;
  }

  input[type="checkbox"]:not(:checked)+.md-expand-content {
    visibility: hidden;
    max-height: 0;
    padding: 0;
  }

  input[type="checkbox"]:not(:checked)~.md-footer {
    visibility: hidden;
    padding: 0;
  }
}

For the tooltips the tooltips CSS library is used.

The headings used within the expand shortcode will show in the table of content, to avoid this one can use the following shortcode to show heading instead:

1

<h{{ .Get 0 }} id="{{ .Get 1 | anchorize }}">{{ .Get 1 | safeHTML  }}</h{{ .Get 0 }}>

Example

{{% expand "Expand example" %}}

{{< h 3 "Example2" >}}

Add any mark-up, shortcode or footnotes here
{{% /expand %}}

Example2

Add any mark-up, shortcode or footnotes here

Noticed an error in this post? Corrections are appreciated.
© Nelis Oostens