HUGOでブログ作成 → GitHub Pagesで公開する手順

· Read in about 12 min · (5829 words) ·

Merry Christmas!
昨日はイブにも関わらず山手線一周して絶賛筋肉痛です。

PyLadies Advent Calendar 2017のラスト記事です。
この記事書き終わったらPyladies Tokyoのアドベントカレンダー完走ですね!

はじめに

PyLadies Advent Calendar 2017に記事を投稿している方々のブログツールを調べたところ、以下のサービスからそれぞれ投稿されてるようです。
・ はてなブログ :6名
・ evernote :2名
・ so-netブログ :1名
・ wordpress :1名
・ アメブロ :1名
・ ipynb :1名
・ twitter :1名
・ Github Pages:1名

twitterやevernoteからも投稿できるのって良いですね。
ブログ書く勢に仲間入りする際にどのツールを使おうかなーと思ってたのですが思ってたのですがマークダウン形式で書きたいし、記事の管理はレポジトリでできたら楽ちんかなーという思いからGithub Pagesを使うことにしました。
自分でサーバー立てなくても使えるって素晴らしい。

ちょうどこの時期に静的サイトジェネレータというツールを使うと、htmlやcssを効率的に作成してくれるということを知ったのでHUGOという静的サイトジェネレータを使ってブログを作ることにしました。

Pyladiesのアドベントなのにpythonのpの文字も出てこず申し訳ないのですがこのまま進めます。
(python関連の記事は来年書きます)

ブログ構築にあたって

そもそも静的サイトジェネレータってなに?ってレベルだったのでそこから調べました。

・静的サイトジェネレータとは
htmlやcssを効率的に作成してくれるサイト構築ツール。
サイト構成には大き分けて動的サイトと静的サイトの2つがあり、前者(動的サイト)はページにアクセスする度にページを生成するのでやや遅め、後者(静的サイト)は既に作ったページを表示させるだけなのでページ遷移が早い、といった特徴がある。
他にも動的サイトの方がページ作成の自由度が高いといった利点もあるけどここでは割愛。
動的サイトや静的サイトの特徴については以下のの記事が分かりやすかったです。

・webdesign-trends https://webdesign-trends.net/entry/2076

・HUGOとは
世の中に数多くある静的サイトジェネレータのうちの1つ。
Go言語で書かれていて、ファイル構造がシンプルだったり、記事生成が早いと言った特徴がある。
HUGOはブログテーマのテンプレートが少ないと言われがちだけど、個人的には2017年12月時点では結構そろってる印象です。モダン系が多め。

調べてみたら他にも色々と静的サイトジェネレータツールを見つけたのでここに載せておきます。
Static Site Generators
StaticGen

ブログと言えばはてなブログしか思いつかないレベルだったので結構調べました。
しかし、いざ作るぞ!となったものの、思った以上にブログ作成に苦戦したので備忘録も兼ねて一連の手順を残しておきます。
(ちなみに苦戦したのは主にGitHubに公開する箇所の手順で、HUGO自体でサイト作成するのはとても簡単です)


ブログ作成→GitHub Pagesで公開する手順

大きく分けて公開するまでに必要な手順は以下です。

①GitHub上に必要なレポジトリを作成&ローカルにclone
②HUGOコマンドを用いてblogサイトを作成する
③作成したローカルレポジトリを↑で作ったリモートレポジトリに移してサブモジュール化する
④リモートレポジトリにpushする

ここで注意してほしいのはHUGOはテンプレートごとに実装されている機能が異なります。
例えばドキュメント作成向けのdocDockというテンプレートにはソーシャルSNS連携機能はないのでブログには向きません。
※もちろん実装すれば可能だとは思いますがそこまで手を加えたくないのであれば最初から機能がついているテンプレートを選ぶのが良いです。

ちなみにこのブログではHugo Bootstrap Premiumというテンプレートを使ってます。
もしファイル構成とか分からなくなったら同じテンプレートを使っている方のレポジトリを覗いてみるのも良いかと思います。
→参考に自分のを載せときます。https://github.com/chanmitsu55/blog

テンプレートは他にもいろいろあるのでここから自分に合うものを探してみてください。

①GitHub上に必要なレポジトリを作成する

HUGOでサイトを作成する前にGithub上に必要なレポジトリを作っておきます。
必要なレポジトリは以下の2個です。どちらもクローンできるようにしたいので初期化にチェックを付けて作成します。

blog といった任意名のリポジトリ
→ソース管理のためのレポジトリ。今回はblogというレポジトリ名で作る
<username>.github.ioのリポジトリ
→公開するためのファイルを置くレポジトリ。

必要なレポジトリについてはブログURLをどういう構成にしたいかで作り方が変わって来ます。
自分はhttps://chanmitsu55(自分のID).github.io/というURLが良かったので必然的にソースと公開ファイルを分けるような上記の方法を取りました。
ルートディレクトリではなくhttps://chanmitsu55.github.io/blogといったgithub.io以下に何かしらのディレクトリを挟むようなURLが良ければレポジトリは1つで十分です。
(詳細はGithubの公式サイトにサイト公開の規則が載っています。)

両方のレポジトリを作成したら、ソース管理の方のレポジトリをローカルの適当な場所にcloneします。  

$ git clone git@github.com:chanmitsu55/blog.git

このREADME.mdしかない空のフォルダにHUGOで作成したサイトを移動させれば、ソースファイルをGithub上で管理できます。

以下、参考にしたサイト。
Configuring a publishing source for GitHub Pages
HugoをGitHub Pagesでホストする方法を考える

②HUGOコマンドを用いてblogサイトを作成する

ここからはHUGOでサイトを作る作業に移ります。まず、HUGOコマンドを使えるようにしたいのでHomebrewでインストール。

$ brew install hugo

インストールできたら以下のコマンドでサイトを作成。
この辺りはHUGOの公式サイト 見たほうが分かりやすいです。

# hugo new site hogeで「hoge」という名前のサイトを構築できます。
$ hugo new site _blog
$ tree
├── archetypes
│   └── default.md
├── config.toml
├── content
├── data
├── layouts
├── static
└── themes
6 directories, 2 files

注) 自分は上記でgit cloneしたディレクトリと同じ配下でサイトを作成したので同名を使わないように_blogとしてます。

上記のディレクトリで操作するのは基本的にcontent配下themes配下config.tomlファイルのみです。

詳細なファイル構成については以下のサイトに詳しく記載されているのでカスタマイズしたい方は参考にどうぞ。

・Let’s HUGO study! http://www.study-hugo.com/basic/knowledge/

ブログ自体のハコはできたのでここからは中身を作成する作業に移ります。

凝り始めると作業の数はどんどん増えていくので、ここでは最低限必要な以下の3つの作業に絞ります。

1.公式サイトから選んだサイトのテンプレートの適用  
2.ブログ記事を作成する  
3.設定ファイル(config.toml)の編集  

1.公式サイトから選んだサイトのテンプレートの適用
使いたいテーマのGithubレポジトリからthemes配下にgit cloneするだけです。

$ cd themes
$ git clone git@github.com:appernetic/hugo-bootstrap-premium.git
$ ls
hugo-bootstrap-premium

2.ブログ記事を作成する
themes配下から一旦抜けてhugo new post/hoge.mdコマンドで記事を作成します。 (hugoコマンドはconfig.tomlが存在する場所で使用します。)
上記のコマンドでcontent配下postというディレクトリが作成され、その中にhoge.mdというマークダウン形式のファイルが作成されます。
原則、ブログの記事は全てpost配下に置きます。

$ cd ..
$ hugo new post/first_content.md

ここではfirst_content.mdというファイルを作り、これを編集していきます。

---
title: "First_content"
date: 2017-12-25T19:10:04+09:00 
draft: true   
---

作ったばかりのファイルに記載されている上記の内容はfront matterと言われる記事の設定をするための決まり事を記載する箇所です。
ここでは以下のように追加タグ付けやカテゴライズの設定を追加しておきます。

---
title: "HUGOでブログ作成  →  GitHub Pagesで公開する手順"
date: 2017-12-25T14:36:54+09:00 # 作成日時が入る
draft: true # trueの場合は下書き状態。このままビルドしてもサイトには表示されな
categories: ["HUGO"]
tags: ["GitHub","HUGO"]
---

本文はその下にマークダウン形式で書いていきます。
冒頭でも述べましたが、HUGOはテーマごとにfront matterも異なるので各テーマのfront matter形式に沿って書いてください。

記事を書きながら逐一確認できるように以下のコマンドでローカルを立ち上げておくと常にレンダリングされて確認しやすいです。

$ hugo server -D -t hugo-bootstrap-premium 

hugo serverはローカルで立ち上げるためのコマンド、 -Dはdraft=true(=下書きにになっている)記事でもビルドしてくれるオプション、-t (テーマ名)は指定のテーマでサイトを表示させるオプション。テーマを指定しないと真っ白なサイトが立ち上がります。
ちなみにhugo serverで立ち上げてもメモリ上にビルドされるだけなので、この時点では公開用のファイルは作成されていません。

3.設定ファイル(config.toml)の編集
これもテーマごとに異なります。 初期状態では2〜3行しか記載されていないので、必要な設定を追加していきます。
以下はhugo-bootstrap-premiumテンプレートにおける一例です。(自分のconfig.tomlから持ってきました)
ここでは各々の設定について説明は省きますが、一部書き換えてコピペすれば動くはずです。

baseURL = "https://chanmitsu55.github.io/"
languageCode = "ja-jp"
weight = 1
title = "chanmitsu55 blog"
publishDir = "public"  # 公開ファイルのディレクトリ名
theme= "hugo-bootstrap-premium" # 使用するテーマ名
hasCJKLanguage = true # 記事のサマリー機能を有効にする。trueにしないと記事サマリーの文章量が大きくなりすぎる。
paginate = 10 # 一つのページに何個まで記事を載せるか。
paginatePath = "page"

[permalinks]
	post = "/:year/:month/:day/:filename/"
	code = "/:filename/"
	
[author]
	name = "chanmitsu55"
	email = "chanmitsu55@yahoo.co.jp"
	
[params.theme]
	name = "yeti"
  
[params]
	BrandImage = "/logo.png"
	brand = "chanmitsu55 blog"
	topline = "chanmitsu55の技術ブログ"
	footline = "Copyright&copy; <a href='/about/'>chanmitsu55</a>"
	showRightSidebar = true
	highlight = "default"
	twitter  = "chanmitsu55"
	github   = "chanmitsu55"

[[menu.main]]
	name = "Home"
	identifier = "home"
	url = "/"
	weight = -200
	pre = "<i class='fa fa-home'></i>"

[[menu.main]]
	name = "Archives"
	identifier = "archives"
	url = "/post/"
	weight = -180
	pre = "<i class='fa fa-archive'></i>"

[[menu.main]]
	name = "About"
	identifier = ""
	url = "/about/"
	weight = -100
	pre = "<i class='fa fa-info-circle'></i>"

configでどんな設定が行えるかは公式サイト(https://gohugo.io/getting-started/configuration/) に記載されています。

これでブログサイト作成にあたって必要な最低限の作業は完了しました。
最後に以下のコマンドでビルドして公開用のファイルが生成されるか確認します。
(この際に、作成した記事のdraft設定はfalse(=公開設定)になってるか確認してください)

# publicディレクトリが作成され、そこに公開ファイルが出力されます。
$ hugo -t hugo-bootstrap-premium

これでブログサイト作成にあたって必要な最低限の作業は完了しました。
次からはGithub上からcloneしたblogレポジトリにここで作成した_blogサイトを移します。

③作成したローカルレポジトリを↑で作ったリモートレポジトリに移してサブモジュール化する

cloneしたblogレポジトリ内に上で作成した_blogサイトの中身を移します。

$ cp -p -f -R _blog/* blog/

これでpushすれば完了!と言いたいのですが、ソース管理のためのレポジトリ(blog)と公開用のレポジトリ(.github.io)に対してそれぞれ管理を分けれるように設定したいので以下の作業を行います。

# publicディレクトリを削除。
$ rm -rf public
# publicディレクトリを公開先リポジトリとしてサブモジュール化する(最初の設定のときに1回だけ行う)
$ git submodule add -b master git@github.com:<user>/<user>.github.io.git public

ここが一番良くわからなかったです。
なぜrm -rf publicをするのかは公式ドキュメントにも記載がないのでそういうものだということにしておきます。
サブモジュール化という意味がよく分からなかったので調べました。

サブモジュール化とは
プロジェクトA内の一部機能Bを別のプロジェクトCから使いたい場合に、その共通して使いたい機能Bを元々のプロジェクトAから切り離して管理すること。
機能Bを更新すれば、それを参照しているプロジェクトA,Cはどちらも最新の機能Bを扱うことができる。

今回で言うと元々https://chanmitsu55(自分のID).github.io/というURLをブログに使いたかったのでソースと公開ファイルを分ける必要があり、公開用ファイルであるpublicを別レポジトリで切り出して<user>.github.ioレポジトリ化で管理するためにサブモジュール化を行っています。
こうすることでソースファイルを更新すれば公開用ファイルも更新されます。

以下、参考にしたサイト。
Qiita:Git submodule の基礎
Git:サブモジュール化
Host GitHub User or Organization Pages

④リモートレポジトリにpushする

ここまで来たらリモートレポジトリにpushしてGitHub上で公開作業を行うだけです。
後々、記事を挙げる度にデプロイする際、何度もコマンドを打つのは面倒なのでスクリプト化します。(公式サイトのほぼコピペ)

#!/bin/bash

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

# Build the project.
hugo -t hugo-bootstrap-premium

# 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 ..

# Commit source repository changes
git add .
git commit -m "$msg"
git push

あとはこれを実行すれば完了です。

$ ./deploy.sh

デプロイが通った後にhttps://<user>.github.io/というURLにアクセスすればブログが公開されているはずです。

コメント機能をつけたり、サイトのロゴを変更したり色々カスタマイズできるのですがそのやり方は別記事でまとめます。


終わりに

ブログ作成までに1分もかからないはてなブログは優秀だなあと感じました(小並)
ちゃんとしたHPを作った事がなかったので公開用ディレクトリの中身とかを読むと結構勉強になりました。
未だにaboutページとか作れてないし、まだまだ不完全なブログなのでもっと充実させていきたいです。