HugoとCircleCIでGitHub PagesにBlogを公開してみた

2015-04-17

hori-ryota.github.io みたいな、GitHub ドメインの技術ブログかっこいいよね〜と思ったので流行りの Hugo と CircleCI を組み合わせて作ってみました。無料。

それぞれのツールを軽く紹介した上で、実際に設定した手順をのせておきます。Mac 用。

まだ作ったばかりなので設定漏れしているところとか画像の最適化がまだだったりとか色々ありますが、とりあえず公開まではこじつけられるかと思います。

完成後の記事作成フロー

記事の作成フローはこんな感じになります。お気に召さなければ違うツールのほうがいいかもです。

hugo new post/aritcle-title.mdで記事の作成
Markdown 形式で記事を書く
git で push する
CircleCI が push を検知して自動公開

CircleCI を使うことで push ≒ 公開になるので楽。

Hugo とか CircleCI とか GitHub Pages とかって何

まずはざっくり説明。

Hugo

Hugo :: A fast and modern static website engine

Go 言語で書かれた静的サイトジェネレーター。静的サイトジェネレーターというのはテンプレや記事のテキストデータから html などなど、公開用のデータを静的に吐き出してくれるやつ。

ブログといえば WordPress というイメージがありますが、アクセス集中すると重いし、セキュリティも面倒だし…というのでなんか重宝されてきているらしい。

GitHub Pages に投げとけば無料だし、エンジニアっぽい（小並感）し。

Markdown で書いておけば、他のツールを使いたくなった時の移行コストも少ないと思われるので、始める心理的な障壁が低いのも良い。

OctopressとかHexoとかもありますが、Hugo の方が変換が爆速らしいっていうのと、Go 言語っていうのにミーハー心を刺激され、Hugo にしてみました。

CircleCI

CircleCI

いわゆる CI ツール。Jenkins とか TravisCI とか。

基本的には GitHub に Push されたコードを何か色々処理してくれるという感じのやつ。

Hugo は変換までしかやらずにデプロイとかは人任せなので、CircleCI で公開は行うようにします。なんか聞きなれないと難しそうだけど、やったら簡単でした。

Jenkins は自分で用意するのが面倒で、TravisCI は Private リポジトリが有料。

CircleCI は並列性に課金する料金システムなので、並列性 0 の順次ビルドであれば Private リポジトリでも無料。すごい。

GitHub Pages

GitHub に静的 Web コンテンツをあげておくと Web ページとして見られるようにしてくれる GitHub のすばらしい機能。無料。ありがたい。

実は 2 種類あって

ユーザー名.github.io で公開される GitHub Pages
ユーザー名.github.io/リポジトリ名 で公開される GitHub Pages

の 2 種で、Hugo のドキュメント（Hosting on GitHub Pages）に書いてあるのは後者。

今回は前者の ユーザー名.github.io で公開したかったので、そちらの手順をまとめます。

Hugo のインストール

選択肢は 2 つ。Go を使ってgo get github.com/spf13/hugoするか、Homebrew でbrew install hugoか。

Go と Homebrew の入れ方はそれぞれのドキュメントを参照。

ベースのファイルの作成

好きな場所でhugo new site サイト名をすると、サイト名のディレクトリが作成され、その中に色々入ってきます。hugo new site horiblogみたいな。

こんな感じになります。ざっくり。

▸ archetypes/ # categoriesとかtagsとかのメタデータを設定するところ
▸ content/    # 記事データとか、コンテンツデータを置くところ
▸ data/
▸ layouts/
▸ static/     # 静的ファイルを置くところ
  config.toml # 設定ファイル

hugoって叩くと変換が始まりますが、まだなにもない状態。

テーマのインストール

テーマ ≒ 見た目ですね。自作してももちろんいいですが、取り急ぎ拾って使ってみました。

spf13/hugoThemes

このへんからgit submodule add git@github.com:spf13/hugoThemes.git themesしてもいいし、

zyro/hyde-x

このへんからgit submodule add git@github.com:zyro/hyde-x.git themes/hyde-xしても OK。

後者のほうがビルドが早くなるので良さそう。そんなにしょっちゅう変えるものでもないので。

テーマの使い方は実行時に指定してもいいですが、config.toml にtheme = "テーマ名"を指定するのが便利かと思います。

他にも、テーマによって独自の設定パラメータが用意されてたりするので、使うテーマの README.md を参照。

submodule で入れているので、適宜 git submodule update --init --recursive とかやってください。

わからなければ submodule じゃなくてファイルぶっこんでもいいと思います。

リポジトリの作成

GitHub にリポジトリを作る。今回は作成用と公開用で 2 つリポジトリを作ります。

公開用はユーザー名.github.ioで作成。作成用のリポジトリ名はなんでもいいです。私はhoriblogで作成。

作成用はプライベートリポジトリにしておくと下書きとか構成とか見られなくていいけど、まぁ別に公開されちゃってても気にならないならお k。

プライベートリポジトリは課金なので、お財布とご相談してください。

.gitignore の設置

.gitignore にpublic/を追加。

git の設定

$ git init
$ git remote add origin ${自分のgithubの作成用リポジトリ}

で設定。

CircleCI の設定

Add projects - CircleCI

ここから。作った作成用リポジトリを Build Project ボタンで有効化。

で、このままだと CircleCI は作成用のリポジトリにしかアクセスできず、公開用のリポジトリにデータを投げられない（GitHub security and SSH keys - CircleCI）ので、以下の設定を。

CircleCI の作成用リポジトリのやつからProject Settingsで設定画面を開く
PermissonsにあるCheckout SSH keysを開く
Authorize w/ GitHubみたいなそれっぽいボタンがあるので、ぽちっと押して GitHub 認証。
認証が終わると CircleCI の画面に帰ってくるので、今度はCreate and add ユーザー名 user keyみたいなボタンがあるのでぽちっと。

これで他のリポジトリにアクセスできるようになります。簡単でとても良い。

circle.yml の設置

CircleCI のビルド用に circle.yml を設置。この設定ファイルをみて CircleCI がいい感じにビルドしてくれる。

Configuring CircleCI - CircleCI

ファイルを見たほうが雰囲気をつかみやすいと思うので、貼っておきます。

circleci.yaml

checkout:
  post:
    - git submodule sync
    - git submodule update --init --recursive

machine:
  timezone: Asia/Tokyo

dependencies:
  pre:
    - go get -v github.com/spf13/hugo
    - git config --global user.name "CircleCI"
    - git config --global user.email "circleci@example.com"

deployment:
  master:
    branch: master
    commands:
      - git clone git@github.com:hori-ryota/hori-ryota.github.io.git public
      - hugo
      - cd public && git add .
      - cd public && git commit -m "[ci skip] publish"
      - cd public && git push origin master

公開用リポジトリのバージョン管理なんてどーでもいいので、git 周りの設定は割と適当です。

ちなみに、これ作っていきなり push しても content の中身が空っぽだと content ディレクトリが git で管理されないため、CircleCI さんがファイル足らねーよ！って怒ってきます。

まぁ、CircleCI でログも表示されるのでエラーが出たらよしなに。

記事の作成

CircleCI の設定まででひと通りの設定は完了。config.toml をテーマに合わせていい感じに設定する必要はあるけど、後述。

とりあえず記事を作ってみます。

$ hugo new post/article-title.md

を叩くと、 content/post/article-title.md が作成されているはず。これを Markdown で編集すれば記事になる。

上部にメタタグっぽい categories とかがあるのだけど、詳しくはこちら。

Front Matter

デフォルトで入るやつは、テーマもしくは自分のArchetypesの設定に依存します。

この記事だとこんな感じです。

あくまで、hyde-x テーマの場合です。

article-title.md

+++
categories = ["Development", "Hugo", "CircleCI", "GitHub Pages"]
date = "2015-04-17T09:00:00+09:00"
description = "hori-ryota.github.ioみたいな、GitHubドメインの技術ブログかっこいいよね〜と思ったので流行りのHugoとCircleCIを組み合わせて作ってみたら超お手軽だったので手順をまとめてみた。無料。"
keywords = ["Hugo", "CircleCI", "GitHub Pages"]
title = "HugoとCircleCIでGitHub PagesにBlog公開してみた"
slug = "create-blog-with-hugo-and-circleci"

+++

設定項目はテーマにもよるし、困ったら後で置換すればいいや〜って思っていますが、一応以下の様な方針。

categories、tags について
- 普通は category と tags な気がするよね…tags がデフォルトじゃない…？
- category ってディレクトリみたいに記事ごとに一つなイメージあるけど、categories？複数…？
- そもそも category みたいな区分って、SEO が云々って理由以外でブログでは要らないかも…？
- categories を tags として使おう！
- ただし、後で category が欲しくなるかもしれないので、categories の一つ目は category 的なやつにするルールにしておく。
slug について
- URL は title からスペースをハイフンに変換したりしてくれるけど、日本語つらい
- ので、url として使われる slug は明示的に指定。
keywords について
- 適当。categories でいいなぁ…tags の代わりとしてとりあえず入れてみた。
date について
- ファイルの作成日時が入るけど、公開するタイミングで手動で書き換え。ちょっとめんどくさい。スクリプト書こうかな…

基本的にはデフォルト項目からいじらないほうが後で楽だと思ってこんな感じの設定に。

といいつつ、tags がなかったり draft がデフォルトじゃなかったりでちょっと気持ち悪いので、テーマごと書き換えるかも。

config.toml の設定

Configuring Hugo

デフォルトで入っている基本項目に加えて、テーマごとで指定できるパラメータを突っ込めば OK。

とはいえ何か詰まることもあると思うので、参考までに自分のやつを晒しておきます。

アカウント関係は hogehoge に書き換えたので、よしなに置き換えてください。

config.toml

baseurl = "http://hori-ryota.github.io"
languageCode = "ja"
title = "Hori Blog"
theme = "hyde-x"
MetaDataFormat = "toml"
disqusShortname = "hogehoge"

[author]
  name = "Hori Ryota"

[permalinks]
  post = "/blog/:slug/"

[indexes]
  category = "categories"

[params]
  theme = "theme-base-0d"
  highlight = "sunburst"
  googleAnalytics = "UA-00000000-1"

  facebook = "https://www.facebook.com/hogehoge"
  twitter = "https://twitter.com/hogehoge"
  github = "https://github.com/hogehoge"

baseurl の末尾に / を入れるか入れないかで迷ったのですが、テンプレートによって個性があるようで…。hyde-x だと baseurl のあとに / から始まる path をくっつける仕様になっているようなので、今回は / 無し。

記事プレビュー

hugo server ってやるとデフォルトでは http://localhost:1313/ でサイトが見られるようになっているはず。

記事を書くときは hugo server -w ってやっておくと保存の度に更新してくれるから楽です。 -d もつけると下書きも含めてくれます。

記事公開

今回の設定では、git の master ブランチに push すれば CircleCI が動いて更新されてくれる…はず！

おわりに

思ったより簡単に作れたなーという印象。とはいえ画像の最適化とかは自動化できていないので、そのへんも組み込もうか検討中。

Hugo はさくっと作れる使用感は良いのだけど、テーマ周りがちょっとまだ微妙だなーと…。記事のメタ情報も統一されていなくてテーマごとに個性が出ちゃったりとか、なんかそのへんが嫌。

もっと流行って、同じ記事データでさくっと見た目を変えられるようになってくるといいなぁという気持ち。

テーマを自分で作れば解決しますがそこまでは頑張らない。

以上、Hugo と CircleCI で GitHub Pages に Blog を公開する手順のまとめでした。