GitHub Pagesでブログ立ち上げ - Hugoを使う

Fri, Aug 28, 2015
blog github hugo
GitHub Pagesでブログ立ち上げ - Hugoを使う

Table of Contents


GitHub Pagesでブログ立ち上げ - Jekyllのためのツールの続き。 前回は、GitHub Pagesで公開するブログサイトを構築するのに、JekyllとJekyll関連ツールを使おうと四苦八苦したが、結局Jekyllに見切りをつけ、Hugoを使うことに決めた。

Hugoとは

Hugoは、国内では2014年末くらいから盛り上がってきているブログサイト構築ツール。 そのホームページによると、ウェブサイトフレームワークで、静的サイトジェネレータとのこと。

フレームワークと名乗ってはいるが、その正体は、Markdownで書かれた記事を元にブログサイトのソースを生成するコンテントビルド機能と、記事作成(など)を支援するユーティリティ機能を持ったコマンドラインツール。

また、静的サイトジェネレータというのは、静的なサイトを生成するという意味ではなく、静的にサイトを生成するという意味。もっと言えば、WordPressとかがアクセス時にビルドが走るのに対し、Hugoを使った場合は事前にビルド済みのものをサーバにアップロードすることになる、ということ。らしい。WordPressは使ったことがないのでよく知らないが、Hugoのホームページにそう書いてある。 つまり、Hugoは静的なサイトだけを扱うツールってわけではないので、JavaScriptとかを駆使して動的でインタラクティブなページを作ってもいいはず。

Hugoのインストール

インストールガイドに従ってHugoをインストールする。

HugoのGitHub ReleasesからWindows用バイナリをダウンロード。このときはバージョン0.14が最新だったので、hugo_0.14_windows_amd64.zipをダウンロードした。

このzipの中身はhugo_0.14_windows_amd64.exeというバイナリ一つとLICENSE.mdとREADME.mdだけ。 このhugo_0.14_windows_amd64.exeがHugoのすべてなので、これを適当な場所において実行できるようにしとけばよい。 今回は、hugo.batというファイルに以下の内容を書き、PATHの通ったフォルダにいれた。

@echo off
C:\Users\Kaito\Desktop\tool\hugo_0.14_windows_amd64\hugo_0.14_windows_amd64.exe %*


これで、どこからでもhugo [arguments]と打てばHugoコマンドが実行できる。

Hugoのシンタックスハイライト

ドキュメントによると、Hugoではシンタックスハイライトを実現する方法を以下の2つから選べる。

  • サーバサイド: Hugoでのブログサイト生成時にハイライトしておく方法。
  • クライアントサイド: クライアントがブログを読み込んだ時にJavaScriptでハイライトする方法。

前者の方が当然クライアントの負荷が軽くなるが、Pygmentsのインストールが必要だったりめんどくさそうなので後者にする。(PygmentsはJekyllのときにすでに入れたけど…)

クライアントサイドでやるのもいくつかやり方があるが、例えばHighlight.jsを使うなら以下をHTMLヘッダに加えるだけでいい。

<link rel="stylesheet" href="https://yandex.st/highlightjs/8.0/styles/default.min.css">
<script src="https://yandex.st/highlightjs/8.0/highlight.min.js"></script>
<script>hljs.initHighlightingOnLoad();</script>

このdefault.min.cssの部分を変えると色々なスタイルが選べる。 このブログではZenburnを使うことにした。

Hugo味見

Hugoコマンドリファレンスを見つつ、Hugoの味見をする。

サイトのひな形を作るコマンドはhugo new site [path]。hugo new site blogを実行して、blogという名のフォルダにサイトの初期ソースを生成。blogの部分はファイルもフォルダも存在しないパスを指定する。

この時点で、blogフォルダ内には以下のものが入っている。

  • archetypes: 新規記事作成時に自動で挿入されるFront Matter (後述)のカスタマイズをするためのファイルを置くフォルダ。
  • content: ブログのコンテンツ(記事など)を置くフォルダ。
  • data: サイト生成時に使うデータを置くフォルダ。
  • layouts: サイトのレイアウトを定義するファイルを置くフォルダ。
  • static: CSSとかJavaScriptとか画像とかのファイルを置くフォルダ。
  • config.toml: 設定ファイル。これはTOMLだが、YAMLかJSONでもいい。


記事を作るコマンドはhugo new [path]。blogフォルダにcdして、二つ記事を作ってみる。

hugo new about.md
hugo new post/first_post.md

blog\content\about.mdとblog\content\post\first_post.mdが生成された。 これらには、Front Matterという、記事のメタ情報が自動で書き込まれる。 デフォルトで書き込まれるのは、日付 (date)、ドラフトフラグ (draft)、タイトル (title)だけだが、 Archetypesという機能でカスタマイズできる。 が、今はやらない。

about.mdとfirst_post.mdには適当に記事の内容を書いておく。


次にテーマを設定する。テーマを使えば、自分でレイアウトを書く必要がない。

テーマはHugo Themesにリストされていて、ひとつひとつ選んでインストールもできるけど、今回は全部いっぺんにインストールして色々見てみる。blogフォルダ内で以下を実行すると、__blog\themes__に全テーマがインストールされる。

git clone --recursive https://github.com/spf13/hugoThemes.git themes


これで、以下のコマンドを実行すると、サイトがビルドされ、サーバが起動し、ブラウザで確認できる。

hugo server -t angels-ladder -D -w

-tでテーマを指定している。指定するのは__blog\themes__内のフォルダ名。-Dはドラフト記事をビルドしたいときにつけるオプション。さっき作ったabout.mdとfirst_post.mdは、そのFront Matterのdraftがtrueになっていて、つまりドラフトなので、-Dを付けないとビルドされない。-wはLiveReloadを有効にするフラグで、付けておくとソースを修正したら自動でリビルドとブラウザのリロードが実行される。(変更を監視されるのはサブフォルダ内だけ。config.tomlの変更は無視される。)

サーバにはhttp://localhost:1313/でアクセスできる。今回指定したテーマangels-ladderだと、トップページにfirst_post.mdの記事へのリンクがあり、その内容を確認できる。about.mdの方はリンクはなく、直接http://localhost:1313/about/アクセスしないと見れない。この辺りはテーマ(と設定?)によって異なるのかな。 まあabout.mdは試しに作ってみただけなので消しておく。

hugo serverの-tに与える値を変えれば簡単にテーマを切り替えられるので、いろいろ見てみる。


以上で味見終わり。

テーマの選定 - Robust

Hugo Themesにあるテーマはどれもあまりしっくりこなかった。 もう自分で作ろうかと思っていたところ、Robustというテーマを見つけた。 こんな感じのページができる。いい。これを使うことにする。

blogフォルダ内で、いったんthemesを消してから以下を実行してRobustをインストール。

> git init .
> git submodule add https://github.com/dim0627/hugo_theme_robust.git themes/hugo_theme_robust

ここでは、git initでblogフォルダをGitリポジトリにして、git submodule addでhugo_theme_robust (RobustのGitHubプロジェクト)をサブモジュールとして追加している。 こうすることで、blogとhugo_theme_robustを別々のリポジトリとして管理しつつ、hugo_theme_robustをblogの一部として使うことができる。


hugo serverするときやビルド時に毎回テーマを指定しなくてもいいように、 config.tomlにtheme = "hugo_theme_robust"を追記しておく。

テーマのカスタマイズ

テーマフォルダ内の構成はblogフォルダ(プロジェクトルート)内と同じようになっていて、Hugoがサイトをビルドするとき、プロジェクトルート内のフォルダとテーマフォルダ内のフォルダをマージしたものを使ってくれる。この際、プロジェクトルート内のファイルが優先される。

つまり例えば以下のような構成のプロジェクトがあったとする。

  • blog
    • layouts
      • hoge.html
    • themes
      • hugo_theme_robust
        • layouts
          • hoge.html
          • foo.html

Hugoはこれをビルドするとき、layouts内にはblog\layouts\hoge.htmlとblog\thmes\hugo_theme_robust\layouts\foo.htmlがあるものとして処理してくれる。テーマをちょっとカスタマイズしたいときに、テーマのソースをいじらないでいいのが便利。


Robustはとりあえず設定ファイルをカスタマイズすれば使える。設定ファイルは、Robustはconfig.yamlだけど、ルートにconfig.toml置いたらちゃんと上書きできた。

記事の仕上げ

first_post.mdの内容を仕上げて、以下のコマンドでdraftフラグをオフにする。

> hugo undraft content\post\first_post.md

これをやるとdateも更新される。

GitHubへソースを保存

blog内の変更をコミットして、GitHubにblogという名のリポジトリを作成して、以下のコマンドでソースをアップロードする。

> git remote add origin [email protected]:kaitoy/blog.git
> git push -u origin master


また、ここで、gh-pagesというブランチを作り、中身を空にして、masterとは別途チェックアウトしておく。 コマンドは以下。

> git checkout -b gh-pages
> rm -rf *
> git rm -rf .
> git commit -m "Init GitHub Pages branch."
> git push origin gh-pages
> git checkout master
> git clone -b gh-pages [email protected]:kaitoy/blog.git pages

これでgh-pagesブランチが__blog\pages__フォルダに展開された。

因みにgh-pagesは、以前のエントリにも書いたが、GitHub Pagesで公開するサイトを置く特別なブランチ。

(2016/8/18追記: 今はgh-pagesブランチは不要。)

ビルド・デプロイ

ビルドコマンドは単にhugo。ビルド成果物はデフォルトでpublicというフォルダに入る。 ここでは、pagesフォルダに入るように以下のコマンドでビルドする。

> hugo -d pages


ビルド完了したら、pagesフォルダにcdして、全てのファイルをgit addして、コミットしてプッシュすればデプロイ完了。 https://kaitoy.github.io/blog/でサイトを確認できる。

カスタムドメイン

サイトにhttp://www.kaitoy.xyzでアクセスできるようにする。手順は以下。

  1. VALUE-DOMAINでkaitoy.xyzを取得。
  2. VALUE-DOMAINのDNS設定にcname tbd kaitoy.github.io.を追加。
  3. gh-pagesブランチのルートにCNAMEというファイルを作り、www.kaitoy.xyzとだけ書いておく。
  4. config.tomlのbaseurlをhttp://www.kaitoy.xyzに変更。ビルドしてプッシュ。

以上でブログサイト立ち上げ完了。あとはテーマをカスタマイズしたり、ひたすらエントリを書く。