2015-04-17

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

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を公開する手順のまとめでした。