Chromwell

Knowledge / Hugo / Basics • 10 min read

Basics

目次

インストール

OS差もあるため、詳細は公式のクイックスタートを参照してください。

https://gohugo.io/getting-started/quick-start/

個人的な備忘を兼ねて、Windows向けの手順を羅列します。

Powershellをインストール（以下すべて管理者モードのPowershellで実行）

Execution Policyを緩和

  Set-ExecutionPolicy AllSigned

Chocolateyをインストール

  Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

HugoのExtended Versionをインストール（Sass利用する場合）

  choco install hugo-extended

Gitをインストール

  choco install git

Dart Sassをインストール

  choco instal sass

サイトを作成したいディレクトリに移動

  cd {お好みのディレクトリ}

サイトを作成

  hugo new site {サイトフォルダ名}

サイトフォルダに移動

  cd {サイトフォルダ名}

Gitリポジトリ作成

  git init

好みのテーマのサブモジュールを追加（例：ananke）

  git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke

利用テーマを指定

  echo "theme = 'ananke'" >> hugo.toml

ローカル起動

  hugo server

問題が発生しがちな部分について、補足します。

  • Windowsの場合、Powershell（※Windows Powershellではない）が必要です。

  • Powershellは、管理者モードで起動してください。

  • いくつかの無料テーマがSassを利用していますが、最新のバージョンだとビルトインのSassビルダーが無効になっているので、Dart Sassを別途インストールする必要があります。

  • また、Sassを利用する場合は、HugoのExtended Versionが必要です。

既存のテーマを利用して、コンテンツだけ増やす

単一ページのサイトで、テーマの活用にもこだわらないのであれば、

  • contentフォルダにmdファイルを追加する
  • hugo.tomlのパラメータのそれっぽい箇所（サイトタイトルやSNSアドレス）を編集する

これでコンテンツ追加して、あなたのサイトとして成立させることが可能です。

ただ、「メニューを増やしたい」「デモサイトと何か違う…」といった問題がすぐに発生するはずです。

問題対処のためには、ページが生成される仕組みについて理解する必要があります。

テーマ編集

ページ生成の流れ

Hugoは、GoをベースとしたSSG（Static Site Generator）であり、プレーンな状態だとCSSやJS要素もほとんどありません。

つまりHTML生成器です。

やっていることは、大雑把にまとめると以下の2点です。

  • コンテンツとなるmdファイルをHTMLに変換して、所定のレイアウトファイル（=HTML）と合成
  • できあがったHTMLファイルに、設定ファイルなどからデータを注入して、最終的な表示内容を生成

なので、以下の2点が理解できれば、自由に編集できるようになります。

  • コンテンツがレイアウトファイルに結び付くルール
  • レイアウトファイルに注入するデータの指定方法

コンテンツがレイアウトファイルに結び付くルール

コンテンツの種類（Kind）

mdファイルに記述することで、コンテンツ個別にレイアウトファイルを割り当てることも可能ですが、基本的にはコンテンツの種類に応じてレイアウトファイルを用意しておくことが一般的です。

Hugoにおいて、コンテンツの種類のことをKindと呼び、Kindは、home、section、page、taxonomy、termsの5種類に分けられています。

Kind 該当するコンテンツ
home contentフォルダのすぐ下にある_index.mdファイル
section contentフォルダの下にあるフォルダの_index.mdファイル
page contentフォルダの下にある_index.md以外のmdファイル
taxonomy （hugo.tomlのtaxonomiesから自動生成）
term （各mdのfront matterに記載のtaxonomy記述から自動生成）

taxonomyは、記事の分類方法です。

デフォルトで、categoryとtagが設定されていますが、hugo.tomlを編集することで任意の分類を追加できます。

termは、記事の分類方法の内訳です。

mdのテンプレート冒頭にある特殊なブロック（front matter）の中で、category = [“料理”, “タイパ”] やtag = [“さかな”, “正月”]などと記述すると、対応するtaxonomyの内訳が増えることになります。

taxonomyとtermは、「一覧へのアクセス方法を提供するためにコンテンツとみなす」くらいに考えておくと良いかと思います。

Kind別の解決先レイアウト

どの種類（Kind）のコンテンツが、どのレイアウトファイルに繋がるのかを具体的に整理すると以下のようになります。

Kind アクセス例 レイアウト解決先 コンテンツmdファイル
home / layouts/index.html content/index.md
section /blog layouts/blog/section.html content/blog/_index.md
page /blog/foo layouts/blog/single.html content/blog/foo.md
/foo layouts/page/single.html content/foo.md
taxonomy /category layouts/category/terms.html -
term /category/blender layouts/category/taxonomy.html -

上の表では、優先度が高い＆汎用性がありそうなサイト構成をイメージして解決先を例示していますが、レイアウト解決のルールは他にも色々あります。

編集中思いがけない所に繋がることもあると思うので、正確な所は、以下の公式ページの中段"Changes to template lookup order"を参照してください。

https://gohugo.io/templates/new-templatesystem-overview/

レイアウト探索が解決できなかった時、下表のようにデフォルトに解決します。

※defaultフォルダが無い場合は、layouts直下に読み替えてください

Kind フォールバック解決先
home layouts/_default/list.html
section layouts/_default/list.html
page layouts/_default/single.html
taxonomy layouts/_default/terms.html（これもなければlist.html）
term layouts/_default/taxonomy.html（これもなければlist.html）

※defaultフォルダを無くすと、taxonomyの解決先はtaxonomy.htmlになります（バグかも）。

レイアウト全体の確定

ここまでで、コンテンツに対して核となるレイアウトファイルが決まります。

核となるレイアウト中にdefine “main"があれば、block “main"を持つHTMLファイル（テンプレだとbaseof.html）と合成されます。

核となるレイアウト中にpartialがあれば、該当のhtmlファイルを呼び出して合成します。

これで、コンテンツを表示する際に必要なレイアウト情報が確定します。

レイアウトファイルに注入するデータの指定方法

設定ファイルやmdファイルの中身にアクセスして、HTMLファイルに埋め込むことができます。

そのデータをさらにソートするなど加工して、ページ全体の生成が完了します。

データアクセスには、Go Html Templateを利用します。（{{}}で囲まれた部分）

アクセス変数

アクセス関数は、Hugoが提供するものと、テーマ製作者が宣言したものがあります。

当然、自身で新しく宣言することも可能です。

変数の前に$がついているものがテーマ製作者由来で、それ以外がHugo提供のものです。

変数の前に.（ピリオド）がついている場合、そのピリオドは現在のコンテクストを指します。

なので、with文やrange文などで操作していく中で対象が変化していく点にご注意ください。

操作関数

操作関数は、Hugo提供、Go Html Template標準のものがあり、以下に情報がまとまっています。

https://gohugo.io/functions/

https://gohugo.io/methods/

用途別にfunctionとmethodに分かれていますが、テーマ編集では両方使います。

HTML中での見分け方は、先頭大文字がMethod、小文字がfunctionです。

テーマ別の仕組み

テーマによって、「hugo.tomlにパラメータを追加すれば、自動的にヘッダーメニューが増える」といった仕組みを実装しているものがあります。

こうした仕組みも、コンテンツツリーによるレイアウト探索（=コンテクストの決定）とHTML外のデータ操作を組み合わせて実装されているので、ここまでの内容を理解することで追えるようになります。

なお、SSGはHTML生成器であり、HTML生成された時点でHTMLの内容は確定していますので、「ユーザーの操作に応じて、見せるデータを変えたい」といったことは、単体ではできません。

例えば、このサイトの「サイト内検索」は、fuse.jsという外部のjavascriptライブラリを導入して実装しています。

デプロイ

デプロイ先は色々選択肢がありますが、ここではfirebaseにデプロイします。 githubなどコードリポジトリを経由せずに、hugo buildの延長線上でアップする感覚でできます。

firebase利用準備

nvmのインストールから準備します。セットアップ済みの部分は適宜読み飛ばしてください。 例によってpowershellは、管理者実行推奨です。

nvm（windows用）のインストーラーを以下で入手してインストール https://github.com/coreybutler/nvm-windows/releases

現在のLTSをインストール

  nvm install --lts

インストールされたバージョンを確認

  nvm list

インストールされているバージョンから利用するものを選択

  nvm use {バージョン}

npmコマンドが使えることを確認

  npm --version

firebase CLIをインストール

  npm install -g firebase-tools

firebaseにログイン

  firebase login

hugoプロジェクトにfirebaseを結合

firebaseプロジェクトを作成

  firebase init

オプションリストは、

  1. Hosting
  2. Use an existing project（既存のfirebaseプロジェクト利用の場合）/Create a new project（新規のfirebaseプロジェクト作成の場合）
  3. そのままEnter（publicフォルダを参照したいため）
  4. No（URLの上書きはしない）

ビルド＆デプロイ

mdファイルのfront matterが、draft = trueのものはアップロードされない点に注意

  hugo && firebase deploy