マニュアル: 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

サイトごとの設定

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

基本項目

  • 必ずセットするもの
    • baseURL: サイトのURL
    • title: サイトのタイトル
    • theme: テーマ名
  • 推奨項目
    • 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ディレクトリに格納するようにしています1

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

contentDir = "post"

taxonomyをtagのみにしたい

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

[taxonomies]
tag = "tags"

.gitignore

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

public/
!post/tags/

コンテンツ管理(content management)

Front Matter

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

ショートコード(shortcodes)

以下のように書きます。

{{< foo >}}

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

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

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

{{</* foo */>}}

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

CSV読み込み

以下のようにします。

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

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

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

テンプレート

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

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

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 }}

よく使うfunction

ページの取得

GetPage

使用例。

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

変数

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

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

ページ変数

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

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

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

ページバンドル

Page Bundles | Hugo

注意点

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

画像処理

Image Processing | Hugo

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

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

  • 出来る(出来た)こと
    • いろいろ
    • テンプレートでエラーが出たときに警告を出す
      • 通常は単に無視されるのですが、警告を出したいこともあります4
      • でもerrorfを使えば可能ですね。
  • 外部ライブラリで出来ること
    • ソースコードのハイライト
    • 数式対応
  • 出来ない(出来てない)こと

  1. Hugo使う前に使ってたJekyllでは_postsという名前を使っていたので、それに近い名前postを選びました。 [return]
  2. Hugo | Configure Hugo [return]
  3. Hugo 0.45: Revival of ref, relref and GetPage | Hugo [return]
  4. Warn about missing templates instead of silently dropping content · Issue #3171 · gohugoio/hugo [return]

逆引きマニュアル