GitHub Pagesとは

GitHubが提供する静的サイトのホスティングサービスです。サーバーを準備する必要がなく、簡単かつ無料でWebページを公開することができるのでとても便利です。

• 静的ファイル(HTML,CSS,javascript,画像)を公開できる。(データベースを用いるような動的なページは公開できない)
• 独自ドメインを割り当てることができる。(別途ドメインの取得が必要)
• ユーザー/組織ページ、プロジェクトページが作成できる。

制限として、ソースリポジトリの容量は1GB以下、ビルドは1時間あたり10回などがあります。詳しくは公式のヘルプを参考にしてください。

What is GitHub Pages? - User Docmentation

HUGOとは

HUGOは、静的なhtmlを生成する事ができる静的ページジェネレータです。HUGOの場合、ローカル環境ではHUGOの動的機能を使って動的にサイトを開発し、成果物の出力時に動的要素を全て静的要素（html,css,js,img等）として出力します。 生成された成果物にはサーバサイドの処理を含まないため、サイトの表示速度は高速になり、サーバサイドの処理が無い分セキュリティリスクが減ります。

参考:HUGOとは？|Let’s study HUGO!!

• ページに必要なHTMLやCSSなどの静的ファイルを作成してくれるジェネレータ
• MarkDown記法で記事を書いてビルドすると必要なファイルが生成される
• テーマを利用すれば簡単にデザインを変更できる
• サーバーサイドの処理がなく高速(記事数が増えてきたら恩恵を感じるかも)

自分でテンプレートを編集する場合はGo Templatesの知識が必要になりますが、基本的にHTMLやjavascript、コマンド実行の経験がある方なら苦労せず導入できます。静的ジェネレータはHUGO以外にもjekyllやGatsbyなど色々あります。高速という点でHUGOを選んでみました。

導入

GitHubの準備

GitHub Pagesにはユーザー/組織ページとプロジェクトページの2種類があります。ここではユーザー/組織ページの手順を紹介します。

1.GitHubリポジトリを作成する

GitHubでリポジトリを作成します。HUGO全体のソースを管理するリポジトリと、公開用ファイルを管理するリポジトリの2つを作成します。

[ユーザー名/組織名].github.io(公開ファイル用)

公開ファイル(HUGOで生成されたpublic配下)を管理するリポジトリ。ここにある静的ファイルがWebページとして公開されます。[ユーザー名/組織名].github.ioという名前で作成する必要があります。

hugo_source(HUGO全体のソース用)

HUGO全体のソースを管理するリポジトリ。名前は任意でOK。Webページ公開において必須ではないですがブログの記事やテンプレート、設定の変更を管理したいので作成します。

HUGOの準備

HUGO公式ページに載っているQuick Startの手順を元に進めていきます。

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

※Homebrewがインストールされていない場合はインストールしてください。 https://brew.sh/index_ja

1.HUGOをインストールする

インストール

brew install hugo

確認

hugo version

2.HUGOプロジェクトを作成する

任意のディレクトリでプロジェクトを作成

hugo new site [プロジェクト名]

3.gitリポジトリ化する

// プロジェクトに移動
cd [プロジェクト名]

// プロジェクトをgitリポジトリ化
git init

4.テーマを追加する

// anankeテーマをsubmoduleとしてリポジトリに取り込む
git submodule add submodule add https://github.com/budparr/gohugo-theme-ananke.git themes/ananke

// config.tomlにanankeテーマを使用する宣言を記述
echo 'theme = "ananke"' >> config.toml

テーマはhttps://themes.gohugo.io/に沢山あります。とりあえずチュートリアルに沿ってanankeを適用します。

submodule化することで外部のリポジトリを自分のリポジトリの管理下に置くことができます。これでテーマのアップデートや修正を追跡することができます。

Git - サブモジュール

5.記事を追加する

hugo new posts/my-first-post.md

コマンドを実行するとcontentディレクトリ内に/posts/my-first-post.mdファイルが作成されます。記事ファイルは/archetypes/default.mdのテンプレートを元に作られます。

my-first-post.mdの内容はデフォルトでtitle:タイトル、date:日付、draft:下書きとなっています。カテゴリやタグの設定をすることも可能です。

---
title: "my-first-post"
date: 2019-02-13T15:30:40+09:00
draft: true
---

6.ローカルブラウザで確認する

hugo server -D

HUGOサーバーを立ち上げhttp://localhost:1313/にアクセスするとページが確認できます。既に1313ポートが使われている場合別のポート番号が割り振られるのでログを確認してください。

-Dオプションは下書き記事もビルド対象に含めます。デフォルトでは作成した記事はdraft: true(下書き状態)になっています。hugo serverで実行すると下書き記事が表示されないことを確認できるかと思います。

7.サイトの設定を記述する

config.tomlファイルを下記のように編集します。

baseURL = "https://[ユーザー名/組織名].github.io/"
languageCode = "ja-jp"
title = "[ホームページタイトル]"
theme = "ananke"

適用するテーマによってはパラメータ項目を記述することでページ内にSNSのアイコンを表示したりボタンの表記を変更したりすることができます。詳しくはテーマごとのgitドキュメントを参考にしてください。

GitHubにHUGOをプッシュする

参考:Host on GitHUB | HUGO

1.HUGOプロジェクトにリモートリポジトリを設定する

HUGOプロジェクトは「HUGOの準備」の項でgit initしリポジトリ化されているのでリモートの情報を設定します。リポジトリはhugo_sourceを指定します。

git remote add origin https://github.com/[ユーザー名/組織名]/hugo_source.git

確認

git remote -v

2.[ユーザー名/組織名].github.ioをsubmoduleとして取り込む

[ユーザー名/組織名].github.ioリポジトリをpublicというディレクトリ名でsubmoduleとして取り込みます。既にpublicディレクトリが存在する場合は先にrm -rf publicで削除してください。

git submodule add -b master https://github.com/[ユーザー名/組織名]/[ユーザー名/組織名].github.io.git public

3.hugoコマンドでビルドする

ビルド

hugo

コマンドを実行するとpublic配下に公開用ファイルが生成されます。

4.公開用ファイルをプッシュする

// publicに移動
cd public

// ステージング
git add .

// コミット
git commit -m "[コミットメッセージ]"

// プッシュ
git push origin master

pushすると[ユーザー名/組織名].github.ioリポジトリに反映されます。反映まで数分かかる場合があります。ここでhttps://[ユーザー名/組織名].github.io/にアクセスすればページが表示されるかと思います。

5.HUGOプロジェクトをプッシュする

HUGOプロジェクト一式をGitHubのhugo_sourceリポジトリにプッシュします。

// publicを出る
cd ..

// ステージング
git add .

// コミット
git commit -m "[コミットメッセージ]"

// プッシュ
git push origin master

記事を更新する

GitHub Pagesを設置する作業は以上です。

記事の更新は基本的に、

1. hugo new [記事タイトル.md]でファイルを作成
2. MarkDown記法で記事を書く
3. hugoでビルドする
4. GitHubのリモートリポジトリにプッシュする

という流れになります。

スクリプトでデプロイを自動化する

上記の手順を手動で行ってもいいのですがシェルスクリプトで自動化します。

vi deploy.sh

HUGOプロジェクト直下にdeploy.shファイルを作成し以下の内容を貼り付けます。

#!/bin/bash

echo -e "\033[0;32mDeploying updates to GitHub...\033[0m"

# Build the project.
hugo # if using a theme, replace with `hugo -t <YOURTHEME>`

# 公開用ファイルのデプロイ
# Go To Public folder
cd public
# Add changes to git.
git add .

# Commit changes.
msg="rebuilding site `date`"
if [ $# -eq 1 ]
  then msg="$1"
fi
git commit -m "$msg"

# Push source and build repos.
git push origin master

# Come Back up to the Project Root
cd ..

# HUGOプロジェクト全体のソースのデプロイ
# Add changes to git.
git add .

# Commit changes.
msg="rebuilding site `date`"
if [ $# -eq 1 ]
  then msg="$1"
fi
git commit -m "$msg"

# Push source and build repos.
git push origin master

これで記事が完成した後にsh deoloy.shコマンドを実行することでビルドからプッシュまでを自動でやってくれます。

まとめ

結構お手軽にWebページを公開することができました。ちょっと簡素なページでもいいから独自ドメインのWebページやブログが欲しいといった場合にいいんじゃないでしょうか。GitHubを使うので技術発信の役目も兼ねていて一石二鳥です。

評価

メリット

• 無料
• サーバーを準備しなくていい、メンテナンスがいらない
• 比較的容易に個人のサイトを開設できる
• 記事の公開が簡単(MarkDown記法)
• テーマを使って簡単にデザインを反映できる
• gitで管理できる、環境が変わっても引越しが簡単
• 独自ドメインを設定できる

デメリット

• 静的ファイルのみ、動的ページは公開できない
• 容量制限があり画像などはあまりアップロードできない
• コマンドでの作業に馴染みがないとハードルがちょっと高い
• オリジナルのデザインを作るには勉強が必要

おわりに

hugoコマンドには色々なオプションがあります。また、config.tomlにパラメータを追加したりdefault.mdをカスタマイズすることでより簡単かつ便利に運用ができそうです。その辺のTipsも今後まとめていきたいと思います。