入門

本文假設讀者已經對程式語言有基礎認知，不會從零介紹所有程式知識，並且在這個基礎認知上介紹 Hugo 的語法。

本文基於基礎範例網站介紹，使用以下指令初始化：

hugo new project my-site --format yaml
cd my-site
hugo new theme test
echo "theme: [\"test\"]" >> hugo.yaml

hugo new theme test 會在 themes/test/ 建立一個主題骨架，主題修改就在這個資料夾進行。

理解專案結構

請見專案結構說明 layouts 目錄以外的結構，以及模板系統說明 layouts 目錄的結構。

平行渲染

Hugo 是多個頁面同時渲染的，務必要記得這點，避免寫出競態的程式碼。雖然你絕大部分時間不會遇到此問題，但是此問題的重要性值得一開始就特別強調。

第一個模板

layouts/home.html：

{{ $v1 := 3 }}
{{ $v2 := 4 }}
<p>{{ add $v1 $v2 }}</p>

<p>7</p>

{{ }} 內是求值的地方，外面原樣輸出。

變數

{{ $price := 100 }}
{{ $price = 120 }}
{{ $price = "特價中" }}
{{ $price }}

特價中

:= 建立，= 賦值。同一個變數可以重複賦值，型別也能中途換掉，這裡 $price 就從數字變成了字串。

函式

{{ add 1 2 3 }}
{{ strings.ToLower "HUGO" }}

6
hugo

函式跟物件無關，是無狀態的：只看你給的參數，同樣的參數永遠回傳同樣的結果，不會因為在哪個模板呼叫而有差異。

上下文

上下文代表「目前位置的上下文內容」。例如在基礎模板 baseof.html 裡面：

{{ . }}

會印出當前頁面的檔案名稱。之後每個模板透過傳遞的上下文決定它接收到什麼資訊，比如同樣在 baseof.html 裡面會看到這樣的呼叫：

{{ partial "head.html" . }}

這代表把「目前頁面（.）」作為上下文（context），傳遞到 head.html 這個模板中。

同理，底下的 {{ block "main" . }}{{ end }} 把目前頁面（.）傳到名為 "main" 的佈局模板裡面，這些 "main" 則在 layouts 目錄的 page、home、section、term、taxonomy 被 {{ define "main" }} 定義。也就是說，這五個佈局模板的 {{ define "main" }} 內部的上下文，同樣也是「目前頁面」。

方法

接在 . 後面呼叫的東西稱為方法，綁定的對象就是 . 代表的上下文本身，不同上下文，同樣的方法回傳結果就不同。

<h1>{{ .Site.Title }} / {{ .Title }}</h1>

.Site.Title 是先呼叫 .Site 拿到網站物件，再對網站物件呼叫 .Title。

把 about 頁面作為變數，呼叫該頁面的 .Title 方法：

{{ $about := .Site.GetPage "/about" }}
{{ $about.Title }}

上下文的切換

<h1>{{ .Title }}</h1>

{{ range slice "蘋果" "香蕉" }}
  {{ . }}<br>
{{ end }}

{{ with "橘子" }}
  {{ . }} / {{ $.Title }}
{{ end }}

<h1>My Site Title</h1>
蘋果<br>
香蕉<br>
橘子 / My Site Title

range、with 裡面，. 換成當下的元素或值；$. 永遠回傳入當前模板最外層的上下文。

管線

不用管線：

{{ strings.ToLower "Hugo" }}
{{ mul 6 (add 2 5) }}

用管線，把值從左邊傳到右邊當最後一個參數：

{{ "Hugo" | strings.ToLower }}
{{ 5 | add 2 | mul 6 }}

兩種寫法結果相同：

hugo
42

註解

Go template 註解，不會出現在輸出裡：

{{/* 不會輸出 */}}

HTML 註解，會照樣輸出到最終的 HTML：

<!-- 會輸出到 html -->

清除空白

Start
{{ if true }}
  true
{{ end }}
End

會渲染成

Start

  true

End

使用 {{- -}} 或是註解使用 {{- /* */ -}} 則可以跨行清除中間空白

Start
{{- if true -}}
  {{- print " %s " "true" -}}
{{- end -}}
End

會渲染成

Start true End

生命週期

變數的生命週期只存在於當前模板，而不是整個當前頁面。當變數是在獨立上下文區塊被建立，上下文區塊結束後變數也自動銷毀。

錯誤：

{{ with "foo" }}
  {{ $x := 1 }}
{{ end }}

{{ $x }}

正確：

{{ $x := 0 }}
{{ with "foo" }}
  {{ $x = 1 }}
{{ end }}

{{ $x }}