モチベーション
自分の興味ある分野について調査したり、試したりした内容をまとめ、保管する場所を考えていた。記述する際には、インターネットのページ参照、シェルプロなどのソースファイルの表示、更には数式も表現できるなどを考えて、マークダウンで記述する事にした。
そのように考えている時に、マークダウンならGitHubが思い浮かび、GitHub Pagesに保管／公開する事にした。
GitHub Pagesは、GitHubがユーザーに提供している静的なウェブページのためのウェブホスティングサービスである。（ウィキペディアより）
参照ページに感謝
このページを参考にした。感謝。
更に、こちらのページも参考にした。同じく感謝。
また、これからの作業を始める前にどのようなページにしたいかを考え、どんなテーマにするかをこちらのページ参考に考えておく。
クライアント環境
自分のクライアント環境は、次のとおり。
- MacBook Pro（2016）
- macOS Catalina バージョン10.15.6
GitHub Pages用のリポジトリ作成
先ずは、公開先のリポジトリを用意する。この節の作業は、ブラウザで行う。
前提として、GitHubのアカウントは既に持っているものとする。
“GitHub アカウント作成"で、検索すれば、qiitaのページ等、かず多くのページが参考にできる。
次の手順で、GitHub Pagesで使用するリポジトリを作成する。
- GitHubにサインインし、「Your repositories」に（トップレベルに）移動
- 右上の＋マークのメニューから「New repository」でリポジトリ作成へ
- 「Create a new repository」のページで次を入力する
- Repository name: foo.github.io（fooは自分のアカウント名）
- その他は、ディフォルトのまま
- 「Create repository」でリポジトリ作成
Hugoをインストール、hugoのプロジェクトを作成
ここからは、Macのターミナルでの作業。
次の手順で、hugoをインストールし、作業するプロジェクト（この例では、blogとのディレクトリ）を作成する。
$ brew install hugo
$ cd ~/workspace
$ mkdir blog
$ hugo new site blog
gitリポジトリの初期化とテーマ選定
自分は、「beautifulhugo」と言うシンプルなテーマを選定した。以下は、このテーマを前提に進める。
$ git init
$ git submodule add https://github.com/halogenica/beautifulhugo.git themes/beautifulhugo
$ cp -r themes/beautifulhugo/exampleSite/* .
$ hugo server
ローカルでテーマ確認
上記でhugoサーバを起動したので、ローカル環境（自分の場合、Macのブラウザ）で、テーマを閲覧する。
- ブラウザで、「http://localhost:1313/」と入力
色々と動きを確認し、どのように自分として変更するかを考える。確認が終われば、端末（上記の「hugo server」と入力した）で、「CTRL＋C」でhugoサーバを終了させる。
設定ファイル（config.toml）を編集
hugoが作成する静的サイトを設定するファイルが、config.tomlである。
このファイルは、これまでの例では、~/workspace/blogにあるので、これをvimなどのエディタで編集する。
自分の場合は、次のような観点で変更した。
- 多言語（日本語、英語）の両方を用意しようかと考えているため、[languages]を追加した。config.tomlへの記述の仕方は、Beautiful Hugoのページに説明がある
- 日本語と英語の実際のページは、contentディレクトリ配下に、jpとenディレクトリを作成し、その各々にpageとpostディレクトリを用意する。
- サンプルページで確認した、右上の「ABOUT」で表示されるページは、postディレクトリ配下にabout.mdで記載する。整理すると、日本語の場合は、~/workspace/blog/content/jp/post/about.mdとなる。
- ブログの記事は、postディレクトリにマークダウン （.md）で格納する。英語のブログ記事をhoge.mdとすると、~/workspace/blog/content/en/post/hoge.mdとなる。
- 記事の先頭に、"—“だけの行で、”tilte: “、”date: “、”tag: “の行を挟むと、ブログトップで、タイトルや日付などが参照できる。テーマのサンプル記事（.mdファイル）を参照を参考に。 これをYAML front matterと言うらしい。TOMLでも使用可能。
- サンプルページで確認した、右上の「samples」は当面使わないが、将来的には、厳選した記事などを直ぐに見れるように活用できそう。
GitHub Pagesとの関連付け
ローカルリポジトリとリモート（GitHub Pages）とを次のようにして関連付ける。
$ git remote add origin https://github.com/akenji3/blog
$ git submodule add -b master https://github.com/akenji3/akenji3.github.io public
上記の「git submodule add」の際に、ローカルにpubulicディレクトが存在すると、有効なレポジトリではないと、次のようなエラーとなる。
つまり、ローカルでhugoで静的ページを作成する前に、上記は実行する。
'public' already exists and is not a valid git repo
GitHubにシェルスクリプトを使ってデプロイ
次のような内容の、deploy.shを作成、実行権を付与する。このシェルプロによって、GitHub Pagesに静的ページを配置（deploy）する。
#!/bin/sh
# If a command fails then the deploy stops
set -e
printf "\033[0;32mDeploying updates to GitHub...\033[0m\n"
# Build the project.
hugo # if using a theme, replace with `hugo -t <YOURTHEME>`
# Go To Public folder
cd public
# Add changes to git.
git add .
# Commit changes.
msg="rebuilding site $(date)"
if [ -n "$*" ]; then
msg="$*"
fi
git commit -m "$msg"
# Push source and build repos.
git push origin master
書き上げた記事を所定のディレクトリに格納して、以下を実行。カレントディレクトリにシェルプロがある場合。
$ ./deploy.sh
気付いたこと
以下に、気付いたことを列挙する。今は一つのみ。これで少しハマった。
- ブログ記事のファイル名をhoge.mdとした場合に、hogeに日本語を含むと、GitHub Pagesでは、トップに要約は掲載されるが、そこから「続きを読む」でページを表示する際に、404のエラーとなる。