高速な静的サイトジェネレータ Hugo の使い方です。 Go 言語に関する記事はこちらへ分離しました。

はじめに

• Hugo とは／Hugo をインストールする
• Hugo で新規の Web サイトを作成する

記事の作成

• Hugo で記事を作成する
• Hugo でドラフトページを作成する
• Hugo でドラフトページの一覧を簡単に確認できるようにする
• Hugo のテーマを設定する
• Hugo で独自のテーマを作成する
• Hugo Themes（Hugo テーマの一覧サイト）

hugo コマンドと設定ファイル

hugo コマンド

• カレントディレクトリを気にせずに hugo コマンドを実行する (hugo server -s)
• ポート番号を指定して Hugo サーバーを起動する (hugo server -p)
• Hugo サーバーで記事生成のキャッシュを無効にする (hugo server --ignoreCache)
• 複数の Hugo サーバーを 1 つのコマンドプロンプト上で立ち上げる
• 複数の Hugo サイトで同じテーマディレクトリを参照する (themesDir)
• 使用していないテンプレートやショートコードを見つける (hugo --printUnusedTemplates)

設定ファイル (config)

• 日本語を正しく扱えるようにしてページサマリーが長くなるのを防ぐ (hasCJKLanguage, isCJKLanguage)
• コンフィグファイルに設定した情報を参照する
• Google アナリティクス用のトラッキングコードを埋め込む (googleAnalytics)
• ページ内に Tex 形式の数式を埋め込めるようにする (MathJax)
• リンクをページからの相対パスで出力するようにする (relativeurls)

Hugo Modules

• Hugo Modules の仕組みで Hugo サイト用のコンテンツを分割して管理する

ショートコード (Shortcode)

ショートコードの使い方と作り方

• ショートコードで本文内に HTML スニペットを埋め込む
• 独自のショートコードを作成する
• ショートコードの中からフロントマターのパラメータを参照する ($.Page.Params)
• ショートコードの中から設定ファイルのパラメータを参照する ($.Site.Params)
• ソースコードをハイライト表示する (highlight)
• ショートコードをエスケープ処理してそのまま表示する
• あるショートコードが使われている場合のみ JavaScript を読み込む (.HasShortcode)
• ショートコードで本文とパラメーターの有無で処理を分岐する

ショートコードの例

• ローカルサーバーで動作させているとき（開発時）のみ内容を出力する private ショートコードを作成する
• SVG ファイルをインラインで埋め込む svg ショートコードを作成する
• クリックで開閉する accordion ショートコードを作成する
• Youtube の動画を表示する youtube ショートコード（Hugo 組み込み）

テンプレート

テンプレートによるレイアウトの基本

• レイアウト用のテンプレートの種類を理解する
• 記事ファイルのフロントマターで使用するレイアウトを制御する (type, layout)
• サイトのヘッダーとフッターをパーシャルファイルに分離する (partials/header.html, partials/footer.html)
• ベーステンプレートを作成して、各種テンプレートの基本構成を統一する (baseof.html)

Hugo のテンプレート文法

• Hugo テンプレート内にコメントを記述する ({{/* ... */}})
• Hugo テンプレート内で変数を扱う ({{ $x := ... }})
• Hugo テンプレート内で配列（スライス）変数を扱う (slice, index, range)
• Hugo テンプレート内でマップ（辞書）変数を扱う (dict, index, range)
• Hugo テンプレート内で if や with で分岐処理する
• Hugo テンプレートで数値によるループ処理を行う (range, seq)
• Hugo テンプレート内で define による部分テンプレート定義を行う（関数もどき）
• Hugo のパーシャルテンプレートから値を返す（関数化）(return)

セクションとページリスト

• Hugo のセクション機能の基本（記事を階層化する）
• セクションテンプレート (section.html) の中でセクションのタイトルを表示する
• セクションの階層構造を取得する (.CurrentSection、.Parent、.Sections)
• ページタイトルに自動でセクションプレフィックスを付ける
• ページの階層構造を取得する関数を作成する (get-hierarchy)
• 一覧表示のサンプルコード
  • サイト内の全ページの一覧を表示する (.Site.Pages)
  • サイト内の全セクションの一覧を表示する (.Site.Sections)
  • カレントセクション直下のページ／セクションの一覧を表示する
  • セクションを持たない記事ページ（ルートの記事ページ）の一覧を表示する (.Site.Home.RegularPages)
  • サイト内の全ページの一覧をセクションの階層構造に従って表示する
  • サイドバー用のページツリーを表示する（現在表示しているページを考慮した階層表示）
  • 最近更新された記事（新着記事）のリストを表示する
  • ページリスト（記事一覧）に列挙されないページを作る (_build.list)
  • セクションページでいろいろな方法でページソートする (.ByDate, .ByTitle, .ByWeight)

タクソノミー（タグとカテゴリー）

• タクソノミーの基本（タグやカテゴリなど）
• タクソノミー関連のテンプレートを定義する
• サイト全体のターム一覧（タグ一覧）を表示する
• 記事ページに付けられたターム一覧（タグ一覧）を表示する
• 記事ページに複数のターム（カテゴリ）を割り当てた場合にエラーにする

data ディレクトリ

• 全ページから参照できるデータを用意する（data ディレクトリ）
• 参照するデータファイルをショートコードのパラメータで切り替える

ページャー（ページネーター）

• ページャー（ページネーター）で複数の記事を切り替えながら表示できるようにする

その他

• パンくずリストを表示する
• JSON-LD のパンくずリストを出力する（SEO 対策）
• 各ページに目次を表示する (.TableOfContents)
• ホームページの Page オブジェクトを取得する
• 各種ページにおいて .Kind や .IsPage、.IsSection、.IsNode の値がどうなるかの一覧
• 次のページ、前のページへのリンクを表示する
• ファイルが存在する場合のみ処理するコードを記述する (fileExists)
• Markdown (.md) ファイルのパス情報を取得する
• Markdown (.md) ファイルを VS Code で開くリンクを表示する
• Markdown ファイルに本文が記述されていない場合だけ特別な出力をする
• テンプレートの中で絵文字を使用する (emojify)

Hugo 応用

• 図／画像
  • 画像ファイルを Markdown ファイルと同じディレクトリに置く (Page Bundle)
  • 大きな画像ファイルから自動的に小さなサムネイル画像を生成する (Image Processing)
  • favicon.ico をサイトのルートに置く (static)
  • mermaid.js で Markdown 中に UML 図を埋め込む
• 検索／サーチエンジン
  • 全文検索（インクリメンタルサーチ）の機能を付ける
  • Google カスタム検索を設置して記事を検索できるようにする
  • サーチエンジン用に robots.txt や sitemap.xml ファイルを配置する
• アドレス／リンク
  • サイト構造を変えてもページの URL が変わらないようにする (Permalink)
  • ページ内リンク（アンカー）を張る
  • 「このページを編集 (Edit this page)」のリンクを表示する
  • 新しいページや別のサイトへ自動でリダイレクトする (aliases, redirectTo)
• Sass/SCSS スタイルシートを使用する
• 特定の記事を常にリスト上方に表示する（weight プロパティ）
• Python で Markdown ファイルのフロントマターの記述が正しいかチェックする
• Facebook や Twitter の SNS で URL をシェアするときの表示設定 (OGP: Open Graph Protocol)
• hugo deploy コマンドで Azure などのクラウドサービス上にデプロイする
• Hugo のテンプレートやショートコードでランダムな文字列を生成する
• 記事ページで TypeScript ファイルや NPM パッケージをインクルードして使用する

トラブルシューティング

• ドラフト指定したセクションが公開されてしまう
• Markdown ファイルに記述した HTML コードが削除されてしまう
• Hugo サーバーで記事の変更内容が反映されない (hugo server --ignoreCache)