マニュアル: Hugo

インストール

バイナリインストール

以下のドキュメント参照。

• Hugo | Install Hugo

コンパイル

前提として、goが入っていること。

go get -v github.com/gohugoio/hugo

特定のバーションをコンパイルするときは、 上のコマンドを実行したあと、以下のようにする。 (例として、GOPATH=~/go、v0.32をコンパイルする場合)

cd ~/go/src/github.com/gohugoio/hugo/
git checkout v0.32
go install

起動オプション

自分がよく使うものです。

• -D: ドラフトを含める
• -F: 未来日を含める
• --bind port: 特定のポートにバインド

サイトごとの設定

これは好みですが、自分は以下のようにしています。

基本項目

• 必ずセットするもの
  • baseURL: サイトのURL
  • title: サイトのタイトル
  • theme: テーマ名
    • テーマはComplete List | Hugo Themesから探します。自作も可能です。
• 推奨項目
  • hasCJKLanguage = “true”: .Summary や .WordCount が日本語を含む東アジアの言語を考慮します。
• オプション項目
  • contentDir = “post” : コンテンツを格納するディレクトリ(詳細は下記)
  • metaDataFormat = “yaml” : MarkdownのFront MatterをYAMLにします(デフォルトはTOML)
• 不要かもしれないもの
  • preserveTaxonomyNames
    • trueにすると、タクソノミー名のé→eへの変換などが行われます。
  • defaultContentLanguege = “ja”
    • 多言語対応の時に、デフォルトで選択される言語です。
  • languageCode = “ja”: 言語コード。たぶんテーマで使います。

Markdownパーサ(BlackFriday)の設定項目

• smartypants = false : 以下の4つを無効にします。好みもありますが、自分はオフです。
  • angledQuotes: “Hugo” → «Hugo»
  • fractions: 分数表示(これは意図されない表示になることが多い)
  • smartDashes: 複数のダッシュ-を変換してくれる
  • latexDashed: LaTeXスタイルのダッシュ変換
• hrefTargetBlank = true : 外部リンクを新規タブでオープンします。

コンテンツを格納するディレクトリを変更

デフォルトではコンテンツはcontentディレクトリに格納しますが、 config.tomlと最初の4文字が同じため、補完しづらく、使いづらいです。 そのため、自分はpostディレクトリに格納するようにしています¹。

この設定は、config.tomlに以下のように書きます²。

contentDir = "post"

taxonomyをtagのみにしたい

デフォルトではtaxonomyはtag(tags), category(categories)の2つが、 定義されていますが、タグしか使わないときは以下のように設定することで、 カテゴリが作成されなくなります。

[taxonomies]
tag = "tags"

.gitignore

以下の設定を入れている。 post/tags/を除外しているのは、Vimの設定と被ってしまうため。

public/
!post/tags/

コンテンツ管理(content management)

• Content Management | Hugo

Front Matter

• Front Matter | Hugo

デフォルトはTOMLのため、YAMLを使う場合は、 ConfigureのmetaDataFormatを変更すること。

ショートコード(shortcodes)

以下のように書きます。

{{< foo >}}

内容によっては、以下のように、閉じるものもあります。

{{< highlight >}}〜〜{{< /highlight >}}

ショートコード自体を埋め込みたい場合は、/*〜*/で囲むとよいみたいです。

{{</* foo */>}}

ビルドインショートコード

• Twitter: tweet ツイートのID

CSV読み込み

• Call the Functions with a URL
• Example for CSV files

以下のようにします。

{{ $dataC := getCSV "separator" "url" }}

注意点は以下になります。

• CSVファイルはdata以下に置かないこと。
• ローカルパスを指定する時は、トップディレクトリ以下の相対パスにする。
  • static以下に置いた場合は、staticから始まるパスを指定する。

テンプレート

Go言語のテンプレートを使用している

HugoはGo言語のテンプレート機能を使用しています。 なので、細かい仕様は以下に書かれている可能性があります。

• template - The Go Programming Language
  • 日本語訳

range

Variablesより、以下のような書式です。

range $index, $element := pipeline

rangeのあとのパラメータが2つの場合はindex(0から始まる)と、要素(element)で、 パラメータが1つだけの場合は要素のみになります。

サイトに書かれている例ではrangeは1つだけですが、 二次元配列のように扱うことができます。 例えば、テーブルにするには以下のようにします。

<table>
{{- $url := .Get "url" }}
{{- range $i, $r := getCSV "," $url }}
{{- $col := $r }}
  <tr>
    {{- if (eq $i 0) }}
      {{- range $r }}
      <th>{{ . }}</th>
      {{- end }}
    {{- else }}
      {{- range $r }}
      <td>{{ . }}</td>
      {{- end }}
    {{- end }}
  </tr>
{{- end }}
</table>

文法

• 条件分岐: {{ if }}〜{{ else if }}〜{{ else }}〜{{ end }}

変数

• サイト(Site)変数
• ページ(Page)変数

よく使うfunction

• デフォルト値: default
• 警告出力: errorf
• そのまま出力
  • HTML: safeHTML

replaceRE

正規表現の注意点として、カッコ自体を記載するときは2回エスケープする必要がある。

• Regex invalid syntax - support - Hugo Discussion

ページの取得

GetPage

使用例。

• セクション: .Site.GetPage "section" "セクション名"
• ページ: .Site.GetPage "page" "ページのパス"
  • 拡張子(.md)が必要。
• タクソノミ(0.45より³)
  • あるタグを取得 .Site.GetPage "/tags/タグ名"

変数

スコープの中で定義した変数は、外では使えません。 そういうときのために.Scratchを使います。

Hugo 0.48以降は外側で定義した変数を、内側で上書きできるようになりました。 文法は{{ $var = "Hugo Home" }}のように、:=でなく=を使います。

• This One Goes to 11! | Hugo

ページ変数

Page Variables | Hugo

ページ変数はFront Matterで定義するが、 必ず小文字で定義すること。

Page-level Params

Page-level .Params are only accessible in lowercase.

空白の制御

Whitespaceにあるように、 開始に{{-と書けば、その前の空白が削除され、-}}と書けば、その後の空白が削除さ れます。 空白は以下の4種類です。

• space → スペース
• horizontal tab → 水平タブ(いわゆる普通のタブ)
• carriage return → キャリッジリターン(CR, ‘\r’)のことかと。
• newline → ラインフィード(LF, ‘\n’)のことかと。

パフォーマンスチューニング

--templateMetricsオプションを使って計測する。

Build Performance | Hugo

目次

Table of Contentsの方法を使えば、目次が出せます。ただしこの方法だと見出しに##(<h2>)から始まるサイトは対応できません。

Issue 1778に回避方法が記載されていますが、自分はJavaScriptでDOMを変更する方法を採りました。なお、このチケットはクローズされていますが、Blackfriday v2に対応することで解決したいようです。

タクソノミ

Taxonomy Templates

Hugo Pipes

• Hugo Pipes Introduction | Hugo

以下のようなものを実現する機能です。

• SASS/SCSS/PostCSSからCSSファイルへの変換
• ファイルの最小化(minification)
• JavaScriptファイルなどのバンドル化
• フィンガープリントやキャッシュバスティングのためのハッシュ

ページバンドル

Page Bundles | Hugo

注意点

• 必ずLeaf BundleまたはBranch Bundle形式にすること。
• 記事を書く場合はLeaf Bundle形式
  • ディレクトリを掘って、そこのindex.mdに記事を書く。
  • 画像などのリソースはそのディレクトリに置く

画像処理

Image Processing | Hugo

iPhoneで撮った画像は横向きが基準で、縦向きで取ると回転が必要なようです。

出来ること・出来ないこと

• 出来る(出来た)こと
  • いろいろ
  • テンプレートでエラーが出たときに警告を出す
    • 通常は単に無視されるのですが、警告を出したいこともあります⁴。
    • でもerrorfを使えば可能ですね。
• 外部ライブラリで出来ること
  • ソースコードのハイライト
  • 数式対応
• 出来ない(出来てない)こと
  • String or Arrayという値は取れない。
    • How to check if a variable is String or Array - support - Hugo Discussion

関連項目

• 辞書: Hugo
• タグ: Hugo

逆引きマニュアル

• Cloud9でHugoを使う方法
• HugoでSass/SCSSを使う方法
• Hugo: CSVを表(テーブル)に変換する方法
• Netlify CMS + Hugo + GitLabの導入方法
• Hugo: 0.45以降でビルドできない
• Hugo: テンプレートを1から作成する方法(最初だけ)
• Hugo: 0.32以降でビルドできない
• Hugoテンプレート: スライドを作成する方法
• Hugo: 静的ファイルに対してCache Bustingを行う方法(0.43以降)
• Hugoテンプレート: 出力されるHTMLを整形する