Hugo と GitHub Pages を使ってサイトを作る

Hugo は Go で書かれた高速な静的サイトジェネレータ。

1 Hugo をインストールする

Quick Start | Hugo も参照。

Mac の homebrew であれば、hugo をインストールすればよい：

brew install hugo

以後は hugo コマンドが利用できるようになる。代表的なのは以下のコマンド：

  • hugo new site NAME: 新しいサイトを空っぽで作る。
  • hugo new PATH: 新しいコンテンツファイルを作る。
  • hugo server: 足元でサイトが見られるサーバを起動する。
  • hugo: サイトをビルドする。

2 新しいサイトを作る

Hugo はサイトジェネレータなので、まずやることは空っぽのサイトを作ること。hugo new site のあとにサイト名を書いて実行する：

hugo new site diary

サイト名のディレクトリが作られるので、移動しておく：

% cd diary
% tree
.
├── archetypes
│   └── default.md
├── config.toml
├── content
├── data
├── layouts
├── static
└── themes

6 directories, 2 files

Directory Structure | Hugo も参照。

3 テーマを入れる

次に、ウェブサイトのデザインを決めるテーマを入れる。

サイト自体を git で管理するなら、git submodule 機能を使うのがよい。Ananke というテーマを使う場合：

git init
git submodule add https://github.com/budparr/gohugo-theme-ananke.git themes/ananke
echo 'theme = "ananke"' >> config.toml

git を使わない場合、普通にテーマの中身を含んだディレクトリ theme ディレクトリ以下にコピーしてもよい。

4 設定ファイルを更新する

さきほどテーマを入れたときに config.toml にテーマの設定を追記したが、それ以外にも設定を更新した方がよい。

config.toml を以下のように書き換える：

baseURL = "公開したときのサイトの URL"
hasCJKLanguage = true # 日本語などを含むときは true
languageCode = "言語 (ja-jp)"
theme = "テーマ名 (ananke)"
title = "サイトのタイトル"

5 新しいページを作る

実際にコンテンツとして、たとえば Markdown でページを作ることができる。content ディレクトリ以下に posts/hello-world.md という Markdown ファイルを作る：

hugo new posts/hello-world.md

実際に content/posts/hello-world.md を開いてみると次のような内容になっている。すでに書き込まれている部分は Front matter といい、メタデータになる。その下に、 Markdown で内容を書く。

---
title: "Hello World"
date: 2020-02-15T04:04:41+09:00
draft: true
---
  • title: ページタイトル
  • date: ページの作成日時
  • draft: 下書きか否か

画像などのリソースファイルは、 static ディレクトリ以下に保存すれば自動でアップロードされる。

6 Hugo サーバを起動する

hugo server コマンドで、足元で Hugo サーバを起動してサイトを見ることができる。-D オプションを付ければ、下書きのコンテンツも見ることができる。

hugo server -D

http://localhost:1313/ でサイトを開くことができる。

7 静的なページをビルドする

hugo コマンドで、サイトを静的なページとしてビルドできる。ここでも -D オプションは利用できる。

hugo -D

public ディレクトリ以下に HTML ファイルなどが生成される。

8 GitHub Pages にデプロイする

GitHub Pages に Hugo でビルドされたサイトをデプロイすることができる。

Host on GitHub | Hugo を参照。

  1. <USERNAME>.github.io という GitHub リポジトリを作っておく。これが GitHub Pages 用リポジトリになる。
  2. config.toml を書き換えて、baseURL = "https://<USERNAME>.github.io/" にする。
  3. 古い public ディレクトリが残っていればいったん削除してから、 git submodule add -b master https://github.com/<USERNAME>/<USERNAME>.github.io.git public で submodule として追加する。
  4. deploy.sh を用意しておけば、あとはこれを実行すれば自動でデプロイされる。
#!/bin/sh

# If a command fails then the deploy stops.
set -e

printf "\033[0;32mDeploying updates to GitHub...\033[0m\n"

# Remove files for obsolete data.
rm -rf public/*

# Build the project.
hugo

# Push to git.
cd public

git add .

msg="rebuilding site $(date)"
if [ -n "$*" ]; then
	msg="$*"
fi
git commit -m "$msg"

git push origin master

上のファイルはほとんど Host on GitHub | Hugo のものと同じだが、もう使われなくなった古いファイルが残ったままデプロイされ続ける問題があるので、rm -rf public/* を追加している。

9 テーマを作る

hugo new theme コマンドで、新しいテーマを作ることができる：

hugo new theme NAME

上のコマンドによって次のようなディレクトリ構造が作られる：

% tree themes/NAME
themes/NAME
├── LICENSE
├── archetypes
│   └── default.md
├── layouts
│   ├── 404.html
│   ├── _default
│   │   ├── baseof.html
│   │   ├── list.html
│   │   └── single.html
│   ├── index.html
│   └── partials
│       ├── footer.html
│       ├── head.html
│       └── header.html
├── static
│   ├── css
│   └── js
└── theme.toml

7 directories, 11 files

テーマでは Go テンプレート機能が活用されているので、参照。template - The Go Programming Language

layouts/_default/baseof.html はベースとなる HTML テンプレート。

<!DOCTYPE html>
<html>
  {{- partial "head.html" . -}}
  <body>
    {{- partial "header.html" . -}}
    <div id="main">
      {{- block "main" . }}{{- end }}
    </div>
    {{- partial "footer.html" . -}}
  </body>
</html>
  • いわゆる <head>...</head> にあたる部分は、 head.html 部分テンプレートを使うようにしている。なので、別に head.html も必要となる。
  • <body>...</body> は大きくヘッダ、メイン、フッタの３つに分かれる。ヘッダとフッタはそれぞれ header.html, footer.html 部分テンプレートを使う。メインだけは少し違っていて、main ブロックを使っている。

部分テンプレートは layous/partials ディレクトリにある。hugo new theme した直後では、layouts/partials/{head,header,footer}.html ファイルはあるものの、すべて中身は空なので、適切に埋めないといけない。

普通の１記事のレイアウトは、layouts/single.html が使われる。記事一覧のレイアウトは、lauouts/list.html が使われる。タグ一覧のようなもののレイアウトは、layouts/terms.html が使われる。あるタグの記事一覧のようなもののレイアウトは、layouts/taxonomy.html が使われる。

トップページは layouts/index.html が使われる。

10 画像を貼り付ける

static ディレクトリに画像ファイルを配置すれば、その画像ファイルはアップロードされて Markdown なら ![](IMAGE_FILE_PATH) で表示できる。

ページタイトル画像は、テーマによるがたとえば featured_image を設定すれば行える（参照：[gohugo-theme-ananke#change-the-hero-background](https://github.com/budparr/gohugo-theme-ananke#change-the-hero-background]）。

11 関連コンテンツ機能

Related Content | Hugoはあるが、自分が欲しいのは Scrapbox の関連ページリスト機能のような機能。

Created at
Tags プログラミング