出来たもの
Nakaji Kohki https://nkjzm.github.io/
[
urlの先の内容が変わって趣旨が伝わらなくならないようにするためのgif
はじめに
知り合いが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の導入
以下のページを見て導入しました。
簡単にまとめると、
(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"
を追記してください。
雑なカスタマイズのイメージ
使用するテーマによって異なる部分もあるので、詳細は各テーマのREADMEやドキュメントを参照してください。
テーマ毎のサンプルページをコピーしてから必要な部分を書き換えていく方法が分かりやすいように思いました。
- サイト全体に関するメタ情報などは
config.toml
に記述していきます。 - 画像は
static/img
以下に格納していきます。 - 各要素やページの内容は
content
以下に記述します。content/home
にトップページの各要素の内容を記述します。content/post
などに記事の内容などを記述します。
Academicテーマ
広く利用されているオープンソースのテーマです。
- MITライセンス
- レスポンシブデザイン
書き方に困ったら僕のリポジトリを参考にしてください。 github.com
Hugoの生成元ファイルと公開対象ファイルを同じリポジトリで管理する
GitHug Pagesのユーザーページはmasterブランチ直下のファイルしか公開できない制約があるため、そのままでは実現できません。
そこで以下の記事が参考になりました。
更新したい場合は、以下の操作を行えばokです。
git push origin source git subtree push --prefix docs/ origin master
余談ですが、2行目の操作をgitのhooks機能を使い、pre-push
で自動化しようと考えました。
参考: gitのpre-push hookでmasterブランチにpushする際にプロンプトで確認するようにする
参考: 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などで出来るだけ周りに発信するように心がけています。しかし、そういった発信を後から参照することは難しいです。実際ある程度交流がある人でも、その人が過去に何をしていたかよく知らないことは多いと思います。そこで、自分の実績やスキル、指向性などがまとまった場所の必要性を改めて感じたのです。
僕はクリエイター気質なので、直接の対話でなくアウトプットを通じて自分を理解した欲しいという想いがあるのですが、そのためにも自分のアウトプットしてきたことを人に伝える努力は怠ってはいけないと思うので、これからも随時更新していきたいと思います。
謝辞
デバッグに協力してくれた@pagu0602に感謝🙏