shortcode 是什麼
有時候我們有些文章排版的想法，在原始的 markdown 中沒有
或者跟內文很難區分，要每次都自己手磋 html 出來又嫌麻煩
Hugo 內建的短代碼 shortcode 是一種將模板整合為小型、可重複使用的片段的方法
雖然 shortcode 在其他地方無法使用，想匯出貼文轉到其他平台會需要另外調整
不過想加入 Markdown 本身不支援的排版，有這點轉換成本還可以接受
語法格式
加 shortcode 進我們的 Hugo 專案其實也不難，大概就3個步驟
- 新增模版 html
- 新增排版的 css
- 在貼文或頁面 markdown 加入使用的語法
shortcode 使用語法
這邊先講在 markdown 裡面使用的語法
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
|
<!-- 使用語法 -->
{{< myshortcode >}}
<!-- 或是 -->
{{% myshortcode %}}
<!-- 需要包住內容時 -->
{{< myshortcode >}}
* a
* b
{{< /myshortcode >}}
<!-- 這是加上註解，跳過轉譯 -->
{{</* myshortcode >}}
* a
* b
{{< /myshortcode */>}}
|
像上面的引用範例，Hugo 會去找 layouts/shortcodes/myshortcode.html 這個檔案來替換內容。
如果想要用資料夾整理也可以。例如 {{<myfolder/myshortcode>}} 就會去找 layouts/shortcodes/myfolder/myshortcode.html。
html模版
這邊我們的模版 html 檔，可以像平常寫 html 一樣、也可以可以傳入參數、抓專案裡面的檔案資源。
傳入參數
我們可以定義在 myshortcode ，用類似 HTML 屬性的方式傳入參數。
如果沒有定屬性名稱，也可以用位置抓值。
1
|
{{< myshortcode "value1" class="my-component" myattr="value2" >}}
|
在 html 檔案內就可以用 Get method 抓到對應的值
1
2
3
4
|
<div class={{ .Get "class" }}>
<p>{{ .Get 0 }}</p>
<p>{{ .Get "myattr" }}</p>
</div>
|
Hugo 轉譯完之後會變為
1
2
3
4
|
<div class="my-component">
<p>value1</p>
<p>value2</p>
</div>
|
傳入包住的內容 Inner
傳入的內容可以使用 $Inner 抓取，看使用情形可以作額外處理。
例如作為一般文字可以包在 <p> 內再輸出到HTML
{{ printf ``<p>%s</p>`` $Inner | safeHTML }}
作為 markdown 做轉譯
{{ .Inner | markdownify }}
抓靜態資源
需要抓靜態檔案的資源，可以使用 resources.GetMatch
例如下面的範例就找 my-project/assets/icons/world.svg
再用 | safeHTML 把SVG檔的內容貼進 HTML
1
2
3
4
|
<div class="logo">
{{- $iconFile := resources.GetMatch "icons/world.svg" -}}
{{ $iconFile.Content | safeHTML }}
</div>
|
抓 data 檔案內的資料
Hugo 可以使用$.Site.Data 去抓 my-project/data/*.toml 內的內容
例如我將內容放在 my-project/data/SVG.html 內
1
|
repository-icon = '<svg xmlns="http://www.w3.org/2000/svg" class="icon" viewBox="0 0 16 16"><path fill-rule="evenodd" clip-rule="evenodd" d="M2 2.5C2 1.83696 2.26339 1.20107 2.73223 0.732233C3.20108 0.263392 3.83696 0 4.5 0L13.25 0C13.4489 0 13.6397 0.0790176 13.7803 0.21967C13.921 0.360322 14 0.551088 14 0.75V13.25C14 13.4489 13.921 13.6397 13.7803 13.7803C13.6397 13.921 13.4489 14 13.25 14H10.75C10.5511 14 10.3603 13.921 10.2197 13.7803C10.079 13.6397 10 13.4489 10 13.25C10 13.0511 10.079 12.8603 10.2197 12.7197C10.3603 12.579 10.5511 12.5 10.75 12.5H12.5V10.5H4.5C4.30308 10.5 4.11056 10.5582 3.94657 10.6672C3.78257 10.7762 3.65442 10.9312 3.57816 11.1128C3.50191 11.2943 3.48096 11.4943 3.51793 11.6878C3.5549 11.8812 3.64816 12.0594 3.786 12.2C3.92524 12.3422 4.0023 12.5338 4.00024 12.7328C3.99818 12.9318 3.91716 13.1218 3.775 13.261C3.63285 13.4002 3.4412 13.4773 3.24222 13.4752C3.04325 13.4732 2.85324 13.3922 2.714 13.25C2.25571 12.7829 1.99929 12.1544 2 11.5V2.5ZM12.5 1.5V9H4.5C4.144 9 3.806 9.074 3.5 9.208V2.5C3.5 2.23478 3.60536 1.98043 3.79289 1.79289C3.98043 1.60536 4.23478 1.5 4.5 1.5H12.5ZM5 12.25V15.5C5 15.5464 5.01293 15.5919 5.03734 15.6314C5.06175 15.6709 5.09667 15.7028 5.1382 15.7236C5.17972 15.7444 5.22621 15.7532 5.27245 15.749C5.31869 15.7448 5.36286 15.7279 5.4 15.7L6.85 14.613C6.89328 14.5805 6.94591 14.563 7 14.563C7.05409 14.563 7.10673 14.5805 7.15 14.613L8.6 15.7C8.63714 15.7279 8.68131 15.7448 8.72755 15.749C8.77379 15.7532 8.82028 15.7444 8.8618 15.7236C8.90333 15.7028 8.93826 15.6709 8.96266 15.6314C8.98707 15.5919 9 15.5464 9 15.5V12.25C9 12.1837 8.97366 12.1201 8.92678 12.0732C8.87989 12.0263 8.81631 12 8.75 12H5.25C5.1837 12 5.12011 12.0263 5.07322 12.0732C5.02634 12.1201 5 12.1837 5 12.25Z"/></svg>'
|
在 html 模版中可以使用 {{ index $.Site.Data.SVG "repository-icon" }} 來抓取內容。
變數、函數
看過上面的用法，Hugo對於包在 {{ }} 中間的用法，就像一般程式在傳參數或調用函式。所以不只有單純顯示，裡面也可以作簡單的邏輯判斷或其他操作。
例如我想判斷一段 shortcode 的 Inner 內容是不是 <p> 開頭，如果不是就強制包進去，我就可以用下面的程式碼做到。先將 markdown 轉譯完的內容放進 content 變數，再做條件判斷。
1
2
3
4
5
6
7
8
9
|
<myshortcode>
{{ $content := .Inner | markdownify }}
{{ if not (strings.HasPrefix $content "<p>") }}
{{ printf `<p>%s</p>` $content | safeHTML }}
{{ else }}
{{ $content }}
{{ end }}
</myshortcode>
|
另外比較常用的 method 就是替換。例如要將 class 從 a 換成 b。
{{ $result := replace $content "a" "b" }}
更多可用的 Method 請參考官網的 Methods
CSS美化
固定主題
我們自訂的css設定可以放在 my-project/assets/scss/custom.scss。
雖然 shortcode 的 css 不會經常改，如果 shortcode 的數量一多，custom.scss 裡面變成一整團，要改也很麻煩。
所以我會把 shortcode 的 css 單讀拆分一個檔案出來，例如在 scss 資料夾內新增 myshortcode.scss，讓 custom.scss 去引用。
1
|
@import "myshortcode.scss";
|
如果想用資料夾整理也可以，例如在 scss 資料夾內新增 myshortcode 資料夾 my-project/assets/scss/myshortcode/main.scss 。
1
|
@import "myshortcode/main.scss";
|
白天、夜晚模式
如果需要讓 shortcode 跟隨白天夜晚模式變化，我們需要用拆分檔案引用方式，不過就不是在 custom.scss 內引用了。
新增 highlight 資料夾 my-project/assets/scss/partials/highlight/
並新增 dark.scss 跟 light.scss 取代原本主題自帶的 scss
各自貼上下面的內容，這些程式碼都是照搬主題原始的 scss
最後就是定好顏色變數，不要跟已有的重複就行了 (下面範例夜晚會出現綠色，白天紅色)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
|
/*
* Style: monokai
* https://xyproto.github.io/splash/docs/monokai.html
*/
$color: #f8f8f2;
$background-color: #272822;
$error-color: #bb0064;
$keyword-color: #66d9ef;
$text-color: $color;
$name-color: #a6e22e;
$literal-color: #e6db74;
// title colors
$type-color: #4B4376;
$title-color: #432E54;
@import "common.scss";
// 在這邊引用
$myshortcode-color:rgb(0, 255, 0);
@import "myshortcode.scss";
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
|
/*
* Style: monokailight
* https://xyproto.github.io/splash/docs/monokailight.html
*/
$color: #272822;
$background-color: #fafafa;
$error-color: #960050;
$keyword-color: #00a8c8;
$text-color: #111111;
$name-color: #75af00;
$literal-color: #d88200;
// title colors
$type-color: #D0E8C5;
$title-color: #C5D3E8;
@import "common.scss";
// 在這邊引用
$myshortcode-color:rgb(255, 0, 0);
@import "myshortcode.scss";
|
這個方式也不限於只有 shortcode 的 scss 能用，像 page 或是其他地方需要修改也可以用這種方式引用。
後面就放意本站有做的 shortcode
嵌入 notion 風格書籤
The world’s fastest framework for building websites.
下載 ICON
到 tabler icon 下載 world svg 檔案，放到 icons 資料夾
my-project/assets/icons/world.svg
Free and open source icons designed to make your website or app attractive, visually consistent and simply beautiful.
新增 bookmark.html
到 layouts 資料夾內新增 shortcodes 資料夾，新增 bookmark.html
my-project/layouts/shortcodes/bookmark.html
1
2
3
4
5
6
7
8
9
10
|
<a href={{ .Get "link" }} target="_blank">
<div class="bookmark">
<div class="logo">
{{- $iconFile := resources.GetMatch "icons/world.svg" -}}
{{ replace $iconFile.Content "icon" "icon bookmark-icon" | safeHTML }}
<span class="name">{{ .Get "name" }}</span>
</div>
<div class="description">{{ .Get "description" }}</div>
</div>
</a>
|
新增 scss
在資料夾 my-project/assets/scss/shortcodes/ 新增 bookmark.scss
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
|
.bookmark {
border: 1.2px solid #d0d7de;
border-radius: 8px;
font-family: -apple-system,BlinkMacSystemFont,segoe ui,noto sans,Helvetica,Arial,sans-serif,apple color emoji,segoe ui emoji;
padding: 1em;
margin-bottom: 20px;
.bookmark-icon {
width: 1.2em;
height: 1.2em;
margin-right: 0.5em;
margin-bottom: -4px;
}
.name {
font-weight: bold;
color: #0969da;
text-decoration: none;
}
.description {
margin-top: 0.5em;
margin-bottom: 1em;
font-size: 90%;
color: #656d76;
transition: all .5s;
font-weight: 400;
}
}
|
my-project/assets/scss/custom.scss 裡加上引用 bookmark.scss
1
|
@import "shortcodes/bookmark.scss";
|
使用方式
在貼文的內容加上下面代碼，就可以產生書籤的效果
1
|
{{<bookmark name="hugo" link="https://github.com/gohugoio/hugo" description="The world’s fastest framework for building websites.">}}
|
Unsplash 引用標籤
在這邊我只想要把引用 unsplash 的文字稍微做區隔
下載 ICON
到 tabler icon https://tabler.io/icons 下載 photo svg 檔案，放到 my-project/assets/icons/ 資料夾
新增 unsplash.html
到 my-project/layouts/shortcodes/ 資料夾(如果沒有就自己建)，新增 unsplash.html
1
2
3
4
5
6
7
|
{{- $raw := (markdownify .Inner | chomp) -}}
{{- $block := findRE "(?is)^<(?:address|article|aside|blockquote|canvas|dd|div|dl|dt|fieldset|figcaption|figure|footer|form|h(?:1|2|3|4|5|6)|header|hgroup|hr|li|main|nav|noscript|ol|output|p|pre|section|table|tfoot|ul|video)\\b" $raw 1 -}}
{{- $icon := resources.GetMatch "icons/photo.svg" -}}
<div class="unsplash unsplash-info" {{ if len .Params | eq 2 }} id="{{ .Get 1 }}" {{ end }}>
<div class="unsplash-title">{{ replace $icon.Content "icon" "icon unsplash-icon" | safeHTML}}</div>
{{- if or $block (not $raw) }}{{ $raw }}{{ else }}<p>{{ $raw }}</p>{{ end -}}
</div>
|
新增 scss
在 shortcodes 資料夾下建立 unsplash.scss
my-project/
└── assets/
└── scss/
├── custom.scss
└── shortcodes/
└── unsplash.scss
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
|
.unsplash {
position: relative;
padding: 1em 1em 2em 2.5em;
margin-bottom: 1em;
border-radius: 4px;
p:last-child {
color: #919eac;
margin-bottom: 0;
}
a {
color: #989bba;
}
p{
margin-left: 20px;
}
.unsplash-title {
position: absolute;
left: 16px;
margin-top: 17px;
font-size: 1.2em;
.unsplash-icon {
color: #919eac;
width: 1.5em;
height: 1.5em;
}
}
&.unsplash-info {
background: #F8FAFC;
border-left: 5px solid #D9EAFD;
}
}
|
custom.scss 裡加上引用
1
|
@import "shortcodes/bookmark.scss";
|
使用方式
在貼文的內容加上下面代碼，就可以出現引用的效果
1
2
3
|
{{ <unsplash> }}
Photo by <a href="https://unsplash.com/@themelessly?utm_content=creditCopyText&utm_medium=referral&utm_source=unsplash">Sho W.</a> on <a href="https://unsplash.com/photos/a-bunch-of-different-shapes-and-sizes-on-a-wall-3tNqoO_ReHQ?utm_content=creditCopyText&utm_medium=referral&utm_source=unsplash">Unsplash</a>
{{ </unsplash> }}
|
terminal 區塊
有時會遇到分享 terminal 指令或執行結果，會想要跟 codeblock 的稍微作區隔
所以就另外做 shortcode 來產生終端機的區塊
同樣的效果 codeblock 我也做了一個版本
Hugo Theme Stack 修改 CodeBlock
$ ls
here is some bash output example
新增 terminal.html
如果你想用 codeblock 表現 terminal 效果，可以參考 Hugo Theme Stack 修改 CodeBlock
在 my-project/layouts/shortcodes/ 新增 terminal.html
這邊利用包住的內容 Inner，當作終端內顯示的內容
由於我寫閉包 shortcode 的習慣，Inner 變數第一行會是一個換行符號，用 replaceRE 可以完美去除
另外就是替換換行符號 \n 跟空白變成 html 格式
空白不替換其實也可以，不過相連的空白就只會顯示一格
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
|
<!-- remove first word is newline -->
{{- $lines := (replaceRE `^\n` "" .Inner) -}}
<div class="terminal">
<div class="terminal-header">
<div class="terminal-btn">
<div class="btn-mac mac-close"></div>
<div class="btn-mac mac-mini"></div>
<div class="btn-mac mac-full"></div>
</div>
{{ if and (ne .Params nil) (isset .Params "title") }}
<div class="terminal-title">{{.Get "title"}}</div>
{{ else }}
<div class="terminal-title">terminal</div>
{{ end }}
</div>
<div class="terminal-block">
<p>{{ $lines | markdownify}}</p>
</div>
</div>
|
新增 scss
我想要終端機有亮暗的模式，所以新增的 terminal.scss 改放在 my-project/assets/scss/partials/highlight/
如果不需要可以自行修改至 my-project/assets/scss/ (記得調整顏色變數)
在 my-project/assets/scss/partials/highlight/ 新增 terminal.scss
程式碼主要參考 codepen 上 Sam Willis 跟 Microk 分享的範例
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
|
/* Fira Code: https://github.com/tonsky/FiraCode */
@import url('https://fonts.googleapis.com/css2?family=Fira+Code:wght@300..700&display=swap');
$font-size: 1.5rem;
$line-height: 1.54em;
.terminal {
border: 1px solid #e6e6e6;
border-radius: 0.7em;
box-shadow: 0 0 24px rgba(0, 0, 0, 0.1);
overflow: hidden;
.terminal-header{
background-color: $terminal-header;
color: $terminal-header-font;
display: grid;
grid-template-columns: 25% auto 25%;
.terminal-title {
-webkit-box-align: center;
-moz-box-align: center;
align-items: center;
display: -moz-box;
-webkit-box-pack: center;
-moz-box-pack: center;
justify-content: center;
text-align: center;
}
.terminal-btn,
.terminal-cp {
padding: 0 6px;
}
.terminal-btn {
display: flex;
.btn-mac {
width: 15px;
height: 15px;
margin: 8px 4px;
border-radius: 50%;
}
.mac-close {
background-color: #ff5f56;
}
.mac-mini {
background-color: #ffbd2e;
}
.mac-full {
background-color: #27c93f;
}
}
.terminal-cp {
align-items: center;
}
}
.terminal-block {
box-sizing: border-box;
margin: 0;
padding: 0;
font-family: "Fira Code", Monaco, Consolas, "Ubuntu Mono", monospace;
font-size: $font-size;
font-weight: 400;
font-style: normal;
line-height: $line-height;
letter-spacing: -0.01em;
background-color: $terminal-background;
color: $terminal-foreground;
text-rendering: optimizeLegibility;
/* -webkit-font-smoothing: antialiased; */
font-feature-settings: "liga", "tnum", "ss01", "locl";
font-variant-ligatures: contextual;
-webkit-overflow-scrolling: touch;
-webkit-text-size-adjust: 100%;
p {
padding: 10px;
margin: 0;
}
}
}
|
然後就是修改 my-project/assets/scss/partials/highlight/ 裡的 dark.scss 跟 light.scss 內分別加入顏色變數還有引用
1
2
3
4
5
6
7
|
// terminal
$terminal-header: #273138;
$terminal-header-font: #ffffff;
$terminal-background: #000000;
$terminal-foreground: #4EEE85;
@import "custom/terminal.scss";
|
1
2
3
4
5
6
7
|
// terminal
$terminal-header: #f4f4f7;
$terminal-header-font: #000000;
$terminal-background: #ffffff;
$terminal-foreground: #000000;
@import "custom/terminal.scss";
|
使用方式
user@host folder % ls
here is some bash output example
1
2
3
4
5
|
{{<terminal>}}
user@host folder % ls
here is some bash output example
{{</terminal>}}
|
裡面的指令開頭，如 user@host folder % 我就沒有另外做生成，需要再手動打上去
一是懶得做辨識指令跟輸出，是個大工程
二是有些單純分享指令的情況，我不會加上開頭，方便複製
只有在同時貼指令加輸出結果時，為了區分會加
再加上裡面的內容有時我會想照不同終端機修改，例如 bash 是 $、mac 的終端機是 %
預設上方的標題會寫 terminal ，如果想換別的可以用 title 屬性修改
$ ls
here is some bash output example
1
2
3
4
5
|
{{<terminal title="bash">}}
\$ ls
here is some bash output example
{{</terminal>}}
|
參考資料
