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

2 minute read

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

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

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

完成後の記事作成フロー

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

  1. hugo new post/aritcle-title.mdで記事の作成
  2. Markdown形式で記事を書く
  3. gitでpushする
  4. 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 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 -v 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 [email protected]:spf13/hugoThemes.git themesしてもいいし、

zyro/hyde-x

このへんからgit submodule add [email protected]:zyro/hyde-x.git themes/hyde-xしてもおk。

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

テーマの使い方は実行時に指定してもいいけど、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の作成用リポジトリ

で設定。commitとかpushとかは他の準備が終わってから。しちゃってもいいけど。

CircleCIの設定

Add projects - CircleCI

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

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

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

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

circle.ymlの設置

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

Configuring CircleCI - CircleCI

細かい説明するよりも、ファイル見せたほうが早いですね

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 "[email protected]"

deployment:
  master:
    branch: master
    commands:
      - git clone [email protected]: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テーマの場合です。

+++
categories = ["Development", "Hugo", "CircleCI", "GitHub Pages"]
date = "2015-04-17T09:00:00+09:00"
description = "hori-ryota.github.ioみたいな、GitHubドメインの技術ブログかっこいいよね〜と思ったので流行りのHugoとCircleCIを組み合わせて作ってみたら超お手軽だったので手順をまとめてみた。無料。"
tags= = ["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

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

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

アカウント関係はhogehogeに書き換えたので、よしなに。

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

comments powered by Disqus