Hugo + GitHub Pages + 無料で洒落たブログを30分で作る

Links

Hugo

https://gohugo.io/
特に説明は書きませんが、おしゃれな静的サイトをすぐに作れるやつです。
例えばブログだと以下の様に、マークダウンで記事を書いて、コマンドを実行すると公開用ファイルが生成されるのでそれをアップロードすると簡単に公開できるというもの。

本体
 ├── 設定ファイル
 ├── マークダウンで書いた記事
 └── 公開用ファイル

Hugo themes

https://themes.gohugo.io/
今回はhello-friend-ngというテーマを使わせて頂く事にしました。

Host on GitHub - GitHub Project Pages

想定の構成

今回は、本体ごとGitHubにあげて、特定のディレクトリ配下だけを自動的にGitHub Pagesとして公開する方法を試すことにしました。

• 公開URL
  https://<アカウント>.github.io/<リポジトリ名>

• 本体をprivateリポジトリにしたかったが...

  • 現状、無料のprivateリポジトリだとGitHub Pages 使えなかった。
    下書きもあるので出来れば本体はprivateで管理したかったがしょうがなくpublicにした。本体と公開用リポジトリを別で管理すれば良いのだけど、今回はやらない。

すでに、たくさんの有用な記事があり、ドキュメントもしっかりしているので特に書くこともないのですが、1ヶ月の自分のために残す事にしました。

公開までの作業

プロジェクト作成

$ brew install hugo
$ cd /path/to/好きなディレクトリ
// blogディレクトリ下にHugoを作っていきます
$ hugo new site blog
// いろいろなファイルができてます
$ ls blog
archetypes/ config.toml content/ data/ layouts/ resources/ static/ themes/

リポジトリ作成

先に、GitHub上で空のリポジトリ(ここでは blog)を作り、リモートURL登録

$ cd blog
$ git remote add origin https://github.com/yotasasaki/blog.git

テーマをSubmoduleで登録

GitのSubmodule管理にしておくとテーマ作成者の変更を後々簡単に反映できるので、今回はそうした。

$ git submodule add https://github.com/rhazdon/hugo-theme-hello-friend-ng.git themes/hello-friend-ng
// いろいろなファイルができてます
$ ls themes/hello-friend-ng 

設定ファイル書き換え

1. まずはテーマ作成者の指示書(How to configure)を読みます。

• 「Just copy:...」 に従って、blog/直下にある config.tomlを上書きします。

1. もう少し様々な設定パターンを見たいときは、exampleSite に置いてある config.tomlを見ると、参考にできます。 GitHubにも公開されています

2. Configure Hugoも参考にできます。

とりあえず変更したのは以下。

• baseUrl
  • https://<アカウント>.github.io/blog がTOPページになる想定なので、書き換え
• piblishDir
  • 本来は公開用ファイルは public/に出力されるが、　ここではGitHub Project Pages の従って、docs/に出力される様に変更。最近また変わったんですかね。こうしておくと、本体ごとmasterブランチにpushしてしまえば、GitHub Pagesで(許可設定さえすれば)自動的にdocs/だけがサイトとして公開されるみたいです。すごい。 GitHub Pages documentation

< baseurl = "/"
---
> baseurl = "https://<アカウント>.github.io/blog"
> publishDir = "docs"


23,24c24,25
<     title = "Hello Friend NG"
<     subtitle = "A simple theme for Hugo"
---
>     title = "好きなブログタイトル"
>     subtitle = "好きなサブタイトル"


<       logoHomeLink = "/"
---
>       logoHomeLink = "/blog"

// ロケールに基づいた上部メニュー設定? 自分はすぐ下の設定の、generic menuを活かしたかったので
// ここはコメントアウトしました。
<     [languages.en.menu]
<       [[languages.en.menu.main]]
<         identifier = "about"
<         name = "About"
<         url = "/about"
<       [[languages.en.menu.main]]
<         identifier = "showcase"
<         name = "Showcase"
<         url = "/showcase"
---
> #    [languages.en.menu]
> #      [[languages.en.menu.main]]
> #        identifier = "about"
> #        name = "About"
> #        url = "/about"
> #      [[languages.en.menu.main]]
> #        identifier = "showcase"
> #        name = "Showcase"
> #        url = "/showcase"

ローカルサーバーで動作確認

$ hugo server -t hello-friend-ng --watch

http://localhost:1313/blog/
で、確認できればOKです。変更がリアルタイムに反映されるので、エディタとブラウザ並べて表示しておくと便利です。

記事作成

• posts/ 下にファイルを作ります。これはconfig.toml上の以下の設定に従うためです。
  [[menu.main]] url = "/posts"

$ hugo new posts/first-article.md
/path/to/blog/content/posts/first-article.md created

Front matterを書き換えます

• draft: false にします。これしないと公開用ファイルが生成されない
• tagsはそれっぽいのを適当に作成
• Front Matterのドキュメントも参照してください

---
title: "はじめまして"
date: 2019-06-30T02:34:27+09:00
draft: false
toc: false
images:
tags:
  - daily
---

Hugoで簡単なブログを作りました。

Aboutページの作成

$ hugo new about.md

同様に、Front matterを書き換えます。

公開用ファイルの生成

$ cd blog/
$ hugo
$ ls docs/
// 公開用ファイル群が生成されてる

簡単！

GitHub Pagesにて公開

まず、GitHubリポジトリのSettingsタブから、Sourceを master branch/docs folder に変更します。
これで、本体をmasterブランチにpushすればその、docsディレクトリの中身だけがGitHub Pagesとして公開されるようになります。先程 config.tomlでpublishDirを変更したのはこの為です。

GitHubにpush

$ git push origin master

https://<アカウント名>.github.io/blog/

に公開されていればOK。

以上です。

注意点やコツ

• キャッシュ
  • 分かっていてもブラウザキャッシュで変わらない事にアレってなりがちなので、ハードリロードする。
  • GitHub側でもキャッシュを持っているのか、正しい設定に直したはずが実際のリンク先がおかしい、みたいな事があり悩んだが10分〜くらい放置したら治ってた...そういうのツライ。
• baseUrl
  • httpから始まるURLにしないと( /blog とかだと)、hugo server が機能しなかった
  • http://localhost:1313で404エラー
• テーマを使う場合は、テーマごとの指示をよく読む
  • exampleSiteのconfig.tomlも参考にする

今回やらなかったこと

• 本体と公開用フォルダの別リポジトリ管理
  • 本体を別のprivateリポジトリにおき、公開用ファイルだけ本リポジトリで管理するとか?
  • git worktree で管理する方法も紹介されていたが、多分意味ない
• ドメインの取得
  • Freenomを使えば無料ドメインが使えて、設定も簡単だがまぁそこまでしなくていいか〜

　
テーマがいろいろあって悩んだり、ちょいとハマったりすると30分では厳しいんですが、同じ構成なら次は30分もかからないはず....！

追記(2022/01)

• faviconの追加
  • テーマのリポジトリ内をfaviconで検索したところドキュメントがあり、指定のサービスで作成した画像をstatic/配下に配置せよ、とのことで、ちゃんと動作もしました。ただ、はじめは変わらず...?となりましたがこのIssueをみてブラウザキャッシュをクリアしたところ正常に適用されました。