Theme Documentation - Shortcodes

2020-03-04 about 2697 words 13 min

LoveIt theme provides multiple shortcodes on top of built-in ones in Hugo.

Hugo uses Markdown for its simple content format. However, there are a lot of things that Markdown doesn’t support well. You could use pure HTML to expand possibilities.

But this happens to be a bad idea. Everyone uses Markdown because it’s pure and simple to read even non-rendered. You should avoid HTML to keep it as simple as possible.

To avoid this limitations, Hugo created shortcodes . A shortcode is a simple snippet that can generate reasonable HTML code and conforms to Markdown’s design philosophy.

Hugo’s Built-in Shortcodes

Hugo ships with a set of predefined shortcodes that represent very common usage. These shortcodes are provided for author convenience and to keep your markdown content clean.

`figure`

Documentation of figure

Example figure Input:

1

{{< figure src="/images/theme-documentation-shortcodes/lighthouse.jpg" title="Lighthouse (figure)" >}}

The rendered output looks like this:

The HTML looks like this:

1
2
3
4
5
6


<figure>
    <img src="/images/theme-documentation-shortcodes/lighthouse.jpg"/>
    <figcaption>
        <h4>Lighthouse (figure)</h4>
    </figcaption>
</figure>

`gist`

Documentation of gist

Example gist Input:

1

{{< gist spf13 7896402 >}}

The rendered output looks like this:

The HTML looks like this:

1

<script type="application/javascript" src="https://gist.github.com/spf13/7896402.js"></script>

`highlight`

Documentation of highlight

Example highlight Input:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


{{< highlight html >}}
<section id="main">
    <div>
        <h1 id="title">{{ .Title }}</h1>
        {{ range .Pages }}
            {{ .Render "summary"}}
        {{ end }}
    </div>
</section>
{{< /highlight >}}

The rendered output looks like this:

1
2
3
4
5
6
7
8


<section id="main">
    <div>
        <h1 id="title">{{ .Title }}</h1>
        {{ range .Pages }}
            {{ .Render "summary"}}
        {{ end }}
    </div>
</section>

`instagram`

Documentation of instagram

Example instagram Input:

1

{{< instagram BWNjjyYFxVx hidecaption >}}

The rendered output looks like this:

View this post on Instagram

A post shared by Bjørn Erik Pedersen (@bepsays) on Jul 6, 2017 at 9:27am PDT

`param`

Documentation of param

Example param Input:

1

{{< param description >}}

The rendered output looks like this:

LoveIt theme provides multiple shortcodes on top of built-in ones in Hugo.

`ref` and `relref`

Documentation of ref and relref

`tweet`

Documentation of tweet

Example tweet Input:

1

{{< tweet 877500564405444608 >}}

The rendered output looks like this:

Hugo 0.24 Released: Big archetype update + @Netlify _redirects etc. file supporthttps://t.co/X94FmYDEZJ #gohugo #golang @spf13 @bepsays
— GoHugo.io (@GoHugoIO) June 21, 2017

`vimeo`

Documentation of vimeo

Example vimeo Input:

1

{{< vimeo 146022717 >}}

The rendered output looks like this:

`youtube`

Documentation of youtube

Example youtube Input:

1

{{< youtube w7Ft2ymGmfc >}}

The rendered output looks like this:

LoveIt Shortcodes

LoveIt provides multiple shortcodes on top of existing ones.

`style`

style is a shortcode to insert custom style in your post.

The style shortcode can use two parameters. The first is the custom style content and the second is the HTML tag around the content you want to change style, and whose default value is p.

Example style Input:

1
2
3


{{< style "text-align: right" >}}
This is a right-aligned paragraph.
{{< /style >}}

The rendered output looks like this:

This is a right-aligned paragraph.

`image`

image shortcode is an alternative to figure shortcode . image shortcode can take full advantage of the dependent libraries of lazysizes and lightgallery.js .

The image shortcode can use the following named parameters:

src

URL of the image to be displayed.
description

Image description.
title

Image title.
class

class attribute of the HTML figure tag.
src_s

URL of the image thumbnail, used for lightgallery.
src_l

URL of the HD image, used for lightgallery.

Example image Input:

1

{{< image src="/images/theme-documentation-shortcodes/lighthouse.jpg" title="Lighthouse (`image`)" src-s="/images/theme-documentation-shortcodes/lighthouse-small.jpg" src-l="/images/theme-documentation-shortcodes/lighthouse-large.jpg" >}}

The rendered output looks like this:

Lighthouse (image) — Lighthouse (`image`)

`admonition`

The admonition shortcode supports 12 types of banners to help you put notice in your page and Markdown format is supported.

Note

A note banner

Abstract

An abstract banner

Info

A info banner

Tip

A tip banner

Success

A success banner

Question

A question banner

Warning

A warning banner

Failure

A failure banner

Danger

A danger banner

Bug

A bug banner

Example

An example banner

Quote

A quote banner

The admonition shortcode can use the following named parameters:

type

Type of the admonition banner, default is note
title

Title of the admonition banner, default is the type name of the banner
details

if true, the content will be expandable/collapsible.

You can also use the positional parameters in the order of type, title and details.

Example admonition Input:

1
2
3
4
5
6
7


{{< admonition type=tip title="This is a tip" details=true >}}
A **tip** banner
{{< /admonition >}}
Or
{{< admonition tip "This is a tip" true >}}
A **tip** banner
{{< /admonition >}}

The rendered output looks like this:

This is a tip

A tip banner

`mermaid`

mermaid is a library helping you to generate diagram and flowcharts from text, in a similar manner as Markdown.

Just insert your mermaid code in the mermaid shortcode and that’s it.

Flowchart

Example flowchart mermaid Input:

1
2
3
4
5
6
7


{{< mermaid >}}
graph LR;
    A[Hard edge] -->|Link text| B(Round edge)
    B --> C{Decision}
    C -->|One| D[Result one]
    C -->|Two| E[Result two]
{{< /mermaid >}}

The rendered output looks like this:

Sequence Diagram

Example sequence diagram mermaid Input:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


{{< mermaid >}}
sequenceDiagram
    participant Alice
    participant Bob
    Alice->>John: Hello John, how are you?
    loop Healthcheck
        John->John: Fight against hypochondria
    end
    Note right of John: Rational thoughts <br/>prevail...
    John-->Alice: Great!
    John->Bob: How about you?
    Bob-->John: Jolly good!
{{< /mermaid >}}

The rendered output looks like this:

GANTT

Example GANTT mermaid Input:

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


{{< mermaid >}}
gantt
    dateFormat  YYYY-MM-DD
    title Adding GANTT diagram functionality to mermaid
    section A section
    Completed task            :done,    des1, 2014-01-06,2014-01-08
    Active task               :active,  des2, 2014-01-09, 3d
    Future task               :         des3, after des2, 5d
    Future task2               :         des4, after des3, 5d
    section Critical tasks
    Completed task in the critical line :crit, done, 2014-01-06,24h
    Implement parser and jison          :crit, done, after des1, 2d
    Create tests for parser             :crit, active, 3d
    Future task in critical line        :crit, 5d
    Create tests for renderer           :2d
    Add to mermaid                      :1d
{{< /mermaid >}}

The rendered output looks like this:

Class Diagram

Example class diagram mermaid Input:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


{{< mermaid >}}
classDiagram
    Class01 <|-- AveryLongClass : Cool
    Class03 *-- Class04
    Class05 o-- Class06
    Class07 .. Class08
    Class09 --> C2 : Where am i?
    Class09 --* C3
    Class09 --|> Class07
    Class07 : equals()
    Class07 : Object[] elementData
    Class01 : size()
    Class01 : int chimp
    Class01 : int gorilla
    Class08 <--> C2: Cool label
{{< /mermaid >}}

The rendered output looks like this:

State Diagram

Example state diagram mermaid Input:

1
2
3
4
5
6
7
8
9


{{< mermaid >}}
stateDiagram
    [*] --> Still
    Still --> [*]
    Still --> Moving
    Moving --> Still
    Moving --> Crash
    Crash --> [*]
{{< /mermaid >}}

The rendered output looks like this:

Git Graph

Example git graph mermaid Input:

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


{{< mermaid >}}
gitGraph:
options
{
    "nodeSpacing": 100,
    "nodeRadius": 10
}
end
    commit
    branch newbranch
    checkout newbranch
    commit
    commit
    checkout master
    commit
    commit
    merge newbranch
{{< /mermaid >}}

The rendered output looks like this:

Pie

Example pie mermaid Input:

1
2
3
4
5
6


{{< mermaid >}}
pie
    "Dogs" : 386
    "Cats" : 85
    "Rats" : 15
{{< /mermaid >}}

The rendered output looks like this:

`echarts`

ECharts is a library helping you to generate interactive data visualization.

The basic chart types ECharts supports include line series , bar series , scatter series , pie charts , candle-stick series , boxplot series for statistics, map series , heatmap series , lines series for directional information, graph series for relationships, treemap series , sunburst series , parallel series for multi-dimensional data, funnel series , gauge series . And it’s extremely easy to create a combinition of them with ECharts.

Just insert your ECharts option in JSON/YAML/TOML format in the echarts shortcode and that’s it.

Example echarts Input in JSON format:

 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


{{< echarts >}}
{
  "title": {
    "text": "Summary Line Chart",
    "top": "2%",
    "left": "center"
  },
  "tooltip": {
    "trigger": "axis"
  },
  "legend": {
    "data": ["Email Marketing", "Affiliate Advertising", "Video Advertising", "Direct View", "Search Engine"],
    "top": "10%"
  },
  "grid": {
    "left": "5%",
    "right": "5%",
    "bottom": "5%",
    "top": "20%",
    "containLabel": true
  },
  "toolbox": {
    "feature": {
      "saveAsImage": {
        "title": "Save as Image"
      }
    }
  },
  "xAxis": {
    "type": "category",
    "boundaryGap": false,
    "data": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"]
  },
  "yAxis": {
    "type": "value"
  },
  "series": [
    {
      "name": "Email Marketing",
      "type": "line",
      "stack": "Total",
      "data": [120, 132, 101, 134, 90, 230, 210]
    },
    {
      "name": "Affiliate Advertising",
      "type": "line",
      "stack": "Total",
      "data": [220, 182, 191, 234, 290, 330, 310]
    },
    {
      "name": "Video Advertising",
      "type": "line",
      "stack": "Total",
      "data": [150, 232, 201, 154, 190, 330, 410]
    },
    {
      "name": "Direct View",
      "type": "line",
      "stack": "Total",
      "data": [320, 332, 301, 334, 390, 330, 320]
    },
    {
      "name": "Search Engine",
      "type": "line",
      "stack": "Total",
      "data": [820, 932, 901, 934, 1290, 1330, 1320]
    }
  ]
}
{{< /echarts >}}

The same in YAML format:

 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


{{< echarts >}}
title:
    text: Summary Line Chart
    top: 2%
    left: center
tooltip:
    trigger: axis
legend:
    data:
        - Email Marketing
        - Affiliate Advertising
        - Video Advertising
        - Direct View
        - Search Engine
    top: 10%
grid:
    left: 5%
    right: 5%
    bottom: 5%
    top: 20%
    containLabel: true
toolbox:
    feature:
        saveAsImage:
            title: Save as Image
xAxis:
    type: category
    boundaryGap: false
    data:
        - Monday
        - Tuesday
        - Wednesday
        - Thursday
        - Friday
        - Saturday
        - Sunday
yAxis:
    type: value
series:
    - name: Email Marketing
      type: line
      stack: Total
      data:
          - 120
          - 132
          - 101
          - 134
          - 90
          - 230
          - 210
    - name: Affiliate Advertising
      type: line
      stack: Total
      data:
          - 220
          - 182
          - 191
          - 234
          - 290
          - 330
          - 310
    - name: Video Advertising
      type: line
      stack: Total
      data:
          - 150
          - 232
          - 201
          - 154
          - 190
          - 330
          - 410
    - name: Direct View
      type: line
      stack: Total
      data:
          - 320
          - 332
          - 301
          - 334
          - 390
          - 330
          - 320
    - name: Search Engine
      type: line
      stack: Total
      data:
          - 820
          - 932
          - 901
          - 934
          - 1290
          - 1330
          - 1320
{{< /echarts >}}

The same in TOML format:

  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


{{< echarts >}}
[title]
text = "Summary Line Chart"
top = "2%"
left = "center"

[tooltip]
trigger = "axis"

[legend]
data = [
  "Email Marketing",
  "Affiliate Advertising",
  "Video Advertising",
  "Direct View",
  "Search Engine"
]
top = "10%"

[grid]
left = "5%"
right = "5%"
bottom = "5%"
top = "20%"
containLabel = true

[toolbox]
[toolbox.feature]
[toolbox.feature.saveAsImage]
title = "Save as Image"

[xAxis]
type = "category"
boundaryGap = false
data = [
  "Monday",
  "Tuesday",
  "Wednesday",
  "Thursday",
  "Friday",
  "Saturday",
  "Sunday"
]

[yAxis]
type = "value"

[[series]]
name = "Email Marketing"
type = "line"
stack = "Total"
data = [
  120.0,
  132.0,
  101.0,
  134.0,
  90.0,
  230.0,
  210.0
]

[[series]]
name = "Affiliate Advertising"
type = "line"
stack = "Total"
data = [
  220.0,
  182.0,
  191.0,
  234.0,
  290.0,
  330.0,
  310.0
]

[[series]]
name = "Video Advertising"
type = "line"
stack = "Total"
data = [
  150.0,
  232.0,
  201.0,
  154.0,
  190.0,
  330.0,
  410.0
]

[[series]]
name = "Direct View"
type = "line"
stack = "Total"
data = [
  320.0,
  332.0,
  301.0,
  334.0,
  390.0,
  330.0,
  320.0
]

[[series]]
name = "Search Engine"
type = "line"
stack = "Total"
data = [
  820.0,
  932.0,
  901.0,
  934.0,
  1290.0,
  1330.0,
  1320.0
]
{{< /echarts >}}

The rendered output looks like this:

`music`

The music shortcode embeds a responsive music player based on APlayer and MetingJS .

The music shortcode can use the following named parameters:

parameter	default	description
url	require	music URL
name	options	music name
artist	options	music artist
cover	options	music cover URL
server	require	music platform: `netease`, `tencent`, `kugou`, `xiami`, `baidu`
type	require	`song`, `playlist`, `album`, `search`, `artist`
id	require	song id / playlist id / album id / search keyword
auto	options	music link, support: `netease`, `tencent`, `xiami`
fixed	`false`	enable fixed mode
mini	`false`	enable mini mode
autoplay	`false`	audio autoplay
theme	`#a9a9b3`	main color
loop	`all`	player loop play, values: ‘all’, ‘one’, ‘none’
order	`list`	player play order, values: ‘list’, ‘random’
volume	`0.7`	default volume, notice that player will remember user setting, default volume will not work after user set volume themselves
mutex	`true`	prevent to play multiple player at the same time, pause other players when this player start play
list-folded	`false`	indicate whether list should folded at first
list-max-height	`340px`	list max height

Custom Music URL

Example music Input:

1

{{< music url="https://rainymood.com/audio1110/0.m4a" name=rainymood artist=rainymood cover="https://rainymood.com/i/badge.jpg" >}}

The rendered output looks like this:

Music Platform URL Automatic Identification

Example music Input:

1
2
3


{{< music auto="https://music.163.com/#/playlist?id=60198" >}}
Or
{{< music "https://music.163.com/#/playlist?id=60198" >}}

The rendered output looks like this:

Custom Server, Type and ID

Example music Input:

1
2
3


{{< music server="netease" type="song" id="1868553" >}}
Or
{{< music netease song 1868553 >}}

The rendered output looks like this:

`bilibili`

The bilibili shortcode embeds a responsive video player for bilibili videos.

When the video only has one part, only the av ID of the video is required, e.g.:

1

https://www.bilibili.com/video/av47027633

Example bilibili Input:

1
2
3


{{< bilibili 47027633 >}}
Or
{{< bilibili av=47027633 >}}

The rendered output looks like this:

When the video has multiple parts, in addition to the av ID of the video, p is also required, whose default value is 1, e.g.:

1

https://www.bilibili.com/video/av36570401?p=3

Example bilibili Input with p:

1
2
3


{{< bilibili 36570401 3 >}}
Or
{{< bilibili av=36570401 p=3 >}}

The rendered output looks like this:

`typeit`

The typeit shortcode provides typing animation based on TypeIt .

Just insert your content in the typeit shortcode and that’s it.

Simple Content

Simple content is allowed in Markdown format and without rich block content such as images and more…

Example typeit Input:

1
2
3


{{< typeit >}}
This is a *paragraph* with **typing animation** based on [TypeIt](https://typeitjs.com/)...
{{< /typeit >}}

The rendered output looks like this:

Alternatively, you can use custom HTML tags.

Example typeit Input with h4 tag:

1
2
3


{{< typeit tag=h4 >}}
This is a *paragraph* with **typing animation** based on [TypeIt](https://typeitjs.com/)...
{{< /typeit >}}

The rendered output looks like this:

Code Content

Code content is allowed and will be highlighted by named parameter code for the type of code language.

Example typeit Input with code:

1
2
3
4
5
6
7


{{< typeit code=java >}}
public class HelloWorld {
    public static void main(String []args) {
        System.out.println("Hello World");
    }
}
{{< /typeit >}}

The rendered output looks like this:

Group Content

All typing animations start at the same time by default. But sometimes you may want to start a set of typeit contents in order.

A set of typeit contents with the same value of named parameter group will start typing animation in sequence.

Example typeit Input with group:

1
2
3
4
5
6
7


{{< typeit group=paragraph >}}
**First** this paragraph begins
{{< /typeit >}}

{{< typeit group=paragraph >}}
**Then** this paragraph begins
{{< /typeit >}}

The rendered output looks like this:

Theme Documentation - Shortcodes

Contents

Hugo’s Built-in Shortcodes

figure

Lighthouse (figure)

gist

highlight

instagram

param

ref and relref

tweet

vimeo

youtube

LoveIt Shortcodes

style

image

admonition

mermaid

Flowchart

Sequence Diagram

GANTT

Class Diagram

State Diagram

Git Graph

Pie

echarts

music

Custom Music URL

Music Platform URL Automatic Identification

Custom Server, Type and ID

bilibili

typeit

Simple Content

Code Content

Group Content

`figure`

`gist`

`highlight`

`instagram`

`param`

`ref` and `relref`

`tweet`

`vimeo`

`youtube`

`style`

`image`

`admonition`

`mermaid`

`echarts`

`music`

`bilibili`

`typeit`