出来たもの

Nakaji Kohki https://nkjzm.github.io/

[ f:id:splas_boomerang:20180610230627g:plain

urlの先の内容が変わって趣旨が伝わらなくならないようにするためのgif

github.com

はじめに

知り合いがGitHubにResume(職務経歴書)をまとめていて良さそうに見えた。

土曜日を1日使ってポートフォリオを公開してみた。

公開まで

技術選定

サーバー: GitHub Pages
静的サイト生成ツール: Hugo (+ Academic)

なるべく手軽に公開できて、かつマークダウンに対応している技術という軸で選びました。

GitHub Pagesで正式サポートされているJekyllも検討しましたが、使いませんでした(後述)。

GitHub Pages

自分でサーバーをホスティングしなくて良い
GitHubに対する操作だけで完結できる
独自ドメインにも対応

サーバーの知識がないので、自分でホスティングしなくて良いのはかなりよいです。また、ホスティングサービスは手軽さ故に放置しちゃう傾向にあると思うのですが、普段から使うGitHubならその心配も少なさそうだと思いました。あと、標準のurlはユーザーidでドメインを発行してくるところも気に入りました。(https://[user_id].github.io/)

Jekyll (不採用)

GitHubが開発してる静的サイト生成ツール
GitHub Pagesで正式サポート
Markdownにも対応

一見良さそうで、ブラウザ上でGithubを操作するだけでもページが作成できてしまうほどしっかりとしたサポートがありました。

Adding a Jekyll theme to your GitHub Pages site - User Documentation

しかし、少しカスタマイズをしようとすると設定が煩雑になり、また反映まで毎回待たされるのがストレスでした。かなり広く使われているツールなので、使いこなせれば便利だと思うのですが、僕の場合後述するhugoの方が使いやすかったです。

Hugo

静的サイト生成ツール
Markdownにも対応
静的ファイルの生成速度が早い

そこまで大きな差はないのですが、導入の容易さと生成速度の速さが良かったです。ただ、Jekyllと違い正式なサポートがないため、一部だけ手間がかかる部分がありました。

Github Pagesの仕様の話

2016年くらいに導入されてからいくつか仕様の変更があったので簡単にまとめようと思います。

gh-pagesブランチの情報がいくつか出てきますが、現状だと使う必要がないので参考にしない方ことをおすすめします。

ページの分類

GitHub Pagesには『ユーザーページ』と『プロジェクトページ』の2種類の仕様が存在します。

	ユーザーページ	プロジェクトページ
用途	ポートフォリオやResume	プロジェクトのWebページ
リポジトリ名	`[user_id].github.io`	`[user_id].github.io/[repository_name]`
付与されるurl	`https://[user_id].github.io/`	`https://nkjzm.github.io/[repository_name]/`
公開対象	masterブランチ直下	masterブランチ直下のフォルダ、もしくは指定ブランチ直下のdocsフォルダ

プロジェクトページは、プロジェクトのソースコード管理と同じリポジトリで管理できるよう、docsフォルダ以下にファイルを置けば良い点が大きく異なると思います。

ユーザーページは直下のファイルしか公開できない制約があるので、今回のような生成元ファイルがある場合の管理が難しかったです(後述します)

利用方法

上記の公開対象にファイルを置いたら、リポジトリのSettingタブから、GitHub Pagesの項目を見つけます。 Sourceで公開対象にするブランチを設定し、Saveします (ユーザーページは自動的にmasterが設定されている模様)

一点注意があって、公開対象に更新があった場合、反映までに少し時間がかかります。

push直後は以下のようなメッセージが表示されます。

Your site is ready to be published at https://nkjzm.github.io/

反映されたら、

Your site is published at https://nkjzm.github.io/

というメッセージに変わります。ミニマム30秒くらい。

失敗すると失敗のメッセージが表示され、メールで通知がきます。その場合公開済みのページが壊れることはなく、失敗前のバージョンが表示され続けます。

参考: qiita.com

Hugoの導入

以下のページを見て導入しました。

qiita.com

簡単にまとめると、

(Macでbrewインストール済みの場合)

brew install hugo
hugo new site hugo-test
cd hugo-test

# サーバー起動
hugo server 

# 静的ファイル生成
hugo

上記の状態だと何も表示されませんが、themeを設定してカスタマイズすることで独自のページを作っていけます。

ローカルサーバーでのプレビュー

http://localhost:1313

からプレビューができます。

これがかなり優秀で、起動しておけばファイルの変更のたびに自動的に更新をしてくれます。

サーバーを落とすときは Controll + C をしないとプロセスが残ることがあるので気をつけましょう。

Github Pagesに向けた設定

hugoコマンドで、public以下に静的ファイルが生成され、これを公開対象に設定することでGitHub Pagesとして表示がされます。しかし、GitHub Pagesの場合公開対象に選べるのはdocsフォルダなので、その設定をしてあげましょう。

config.toml に publishDir = "docs"を追記してください。

参考: Host on GitHub | Hugo

雑なカスタマイズのイメージ

使用するテーマによって異なる部分もあるので、詳細は各テーマのREADMEやドキュメントを参照してください。

テーマ毎のサンプルページをコピーしてから必要な部分を書き換えていく方法が分かりやすいように思いました。

サイト全体に関するメタ情報などは config.tomlに記述していきます。
画像はstatic/img以下に格納していきます。
各要素やページの内容はcontent以下に記述します。
- content/homeにトップページの各要素の内容を記述します。
- content/postなどに記事の内容などを記述します。

Academicテーマ

広く利用されているオープンソースのテーマです。

MITライセンス
レスポンシブデザイン

themes.gohugo.io

書き方に困ったら僕のリポジトリを参考にしてください。 github.com

Hugoの生成元ファイルと公開対象ファイルを同じリポジトリで管理する

GitHug Pagesのユーザーページはmasterブランチ直下のファイルしか公開できない制約があるため、そのままでは実現できません。

そこで以下の記事が参考になりました。

qiita.com

更新したい場合は、以下の操作を行えばokです。

git push origin source
git subtree push --prefix docs/ origin master

余談ですが、2行目の操作をgitのhooks機能を使い、pre-pushで自動化しようと考えました。

参考: gitのpre-push hookでmasterブランチにpushする際にプロンプトで確認するようにする - Qiita

参考: git/hooks--pre-push.sample at master · git/git · GitHub

しかし、while read local_ref local_sha1 remote_ref remote_sha1が動作せず、断念しました。

whileより前の行でecho "hello"を記述するとpush時にhelloが出力されるが、while内の処理が呼ばれない

どなたか原因思い当たる方がいましたらぜひご教授くださいmm

最後に (ポエム)

Github PagesとHugoを使い、手軽に自分のポートレートサイトを作成することができました。

最近思ったのですが、こういった自分の情報を俯瞰して参照できるページはかなり意義があるのではないでしょうか。

僕は普段から技術研鑽やアウトプットをしていると自負していて、Twitterなどで出来るだけ周りに発信するように心がけています。しかし、そういった発信を後から参照することは難しいです。実際ある程度交流がある人でも、その人が過去に何をしていたかよく知らないことは多いと思います。そこで、自分の実績やスキル、指向性などがまとまった場所の必要性を改めて感じたのです。

僕はクリエイター気質なので、直接の対話でなくアウトプットを通じて自分を理解した欲しいという想いがあるのですが、そのためにも自分のアウトプットしてきたことを人に伝える努力は怠ってはいけないと思うので、これからも随時更新していきたいと思います。