Hugoの何がいいか？
Hugoが他の静的サイト作成ツールよりも優れているところはざっと以下です
- Gitですべて管理できる
- デザインテンプレート（over 200例）も準備されているので基本はこれを適応するのでok
- 管理画面なども無くシンプルでわかりやすい/管理しやすい
- config.tomlがもろもろの設定の親ファイルとなるため基本はこれをイジるだけ
- 記事の追加はmdファイルを記事ごとに追加するだけなので複雑/過剰な設定が不要
- シンプルな構成で挙動が早い、ページ表示・遷移が早い
- 変更結果などがクイックに確認できるのでストレスレス（重要）
- Github pagesやnetlifyなどにホストさせれば無料でネットに公開できる
gitが使えることが前提にありますが、使える人にはとにかくシンプルで管理が楽、挙動が早いのでおすすめです。
具体的には、個人のブログ/ポートフォリオ/技術紹介ページなど、サクッと作りたい/手軽に編集管理がしたいという用途にバッチリです。
会社の有志メンバーと公開・運営しているOpenBrainPadもHugo+Github pagesで作成しています。これまで会社から発信した技術記事などをアーカイブしているポートフォリオ的なサイトです。
以下、Hugoでのサイト構築方法が続きますが、具体的なコードを見たい場合はこちらを適宜参照ください。
実行環境
- macOS: Catalina バージョン10.15.5
- Hugo: Static Site Generator v0.64.0/extended darwin/amd64 BuildDate: unknown
- Git: git version 2.24.1
Hugoでローカルにページを作る
ここでは具体的な例として4enki.comというwebページをhugoで作成・公開するまでの手順を示します。hugoのデザインテンプレートはCreative portfolioというテーマを使用しました。こういう感じのものです。
hugo自体のインストール
macならbrewで簡単。
$ brew install hugo
webページの骨格となるファイルたちの生成
$ hugo new site 4enki.com
4enki.com 部分は任意の名前にしてください
以下のファイルが自動で一気に作成されます。
4enki.com
├── archetypes・・・ブログ記事のフォーマットファイルなどが入る
├── config.toml・・・設定ファイルの大本。基本はここを編集する
├── content・・・ブログ記事などはここにmdファイルが設置される
├── data
├── layouts
├── static・・・画像やCSSなどが入る
└── themes・・・インストールしてきたthemeテンプレートが入る
テーマのインストール
ここから好きなやつを選びます
基本は個別のthemeページに記載されているインストール方法に従えばok。
今回は Creative portfolio というテンプレートを選択した場合の方法を一例として記載します。テーマはhugoが生成してくれたthemesディレクトリの中でgit cloneしてゲットします。
$ cd themes
$ git clone https://github.com/kishaningithub/hugo-creative-portfolio-theme.git
$ rm -rf hugo-creative-portfolio-theme/.git
上記のテーマページには続いてテーマカラー、disqusコメントフォーム、google analyticsの指定方法などが続きますが起動に影響するわけではないので後回しでok
重要な処理は、自身のページの最上位ディレクトリ（ここでは 4enki.com/ の下）にある、
- contentディレクトリ
- Static/img ディレクトリ
- Config.tomlファイル・・・設定の親ファイルのため特に重要
をexampleSite下にあるそれぞれのファイルとまるっと入れ変える処理が必要。これを入れ替えないとこの後ローカルでサイトを表示させた時に何も表示されません。処理的には、
$ cd 4enki.com
$ cp -r themes/hugo-creative-portfolio-theme/exampleSite/* .
ローカルでサイト表示
上記までの処理が全て終わったら最上位ディレクトリ（ここでは 4enki.com/)に移動して、以下を実行
$ cd 4enki.com
$ hugo server
起動した状態で、http://localhost:1313/ に行くと demoサイトで見たのと同じデザインのサイトが起動していることがわかります。
Config.tomlファイル内の設定（タイトル部分 title= "xx"）などを編集して表示が変わることを確認してください。hugo serverが動いている間はファイルの変更を自動で検知してリロードを掛けてくれるのでとても便利です。
ちなみに、サイトコンテンツとして新しいページを追加したい場合（例えば新規にブログ記事を執筆する場合など）は、
$ hugo new posts/test.md
コンテンツは contens/ 以下に自動でpostsディレクトリを作成してくれ、その下にmarkdownファイルが追加されていきます。
ブログのフォーマットなどはarchetypes/default.mdに記載されたものになります。
ここまででローカルでのHugo表示は終わり。
GitHub Pagesで公開する
公式のやり方ページはこちら
Hugoでは通常、webページとして公開するhtmlは
$ hugo
というコマンドを実行するだけで public/ というディレクトリを生成し、その下に自動でhtmlファイルを生成してくれる。便利。
ただし、Github Pagesでwebページを公開する場合には、 public/ ではなく docs/ 以下にhtmlを設置しておくルールとなっている（HugoではなくGitHub側のルールらしい）。GitHub Pagesは Hugoのレポジトリの中の docs/ フォルダを探し、その下にあるhtmlファイルをレンダリングしてくれる。
どうやって publicフォルダではなくdocs以下にhtmlファイルを設置するかというと、config.tomlファイルにpublishDir = "docs"の1行を追加するだけ。これだけでhugoコマンドを実行したときにHugo側で自動で publicではなくdocsフォルダを作ってその下にhtmlを生成してくれる。便利。
また、config.tomlファイルにcanonifyurls = trueの1行を追加します。
Hugoでは、作成するwebpageのurlは前提として https://ysdyt.github.io/ のようにgithub.ioの階層で終わることを想定しているそうです。しかし今回の https://ysdyt.github.io/ysdyt.net/ のように、github.ioの下にさらにysdyt.netというディレクトリ階層をもたせた場合、baseurlの前提が異なるため、hugoは意図通りパスをビルドできなくなります。
そこでcanonifyurls = trueとしておくことでbaseurl=に指定したパスを問答無用でbaseurlにしてくれます。
これまでにローカルに作成したコード一式をGithubのremoteレポジトリにプッシュする
まずはremoteに空のレポジトリを作る
- ここでは https://github.com/ysdyt/4enki.com/ というレポジトリを作成した
$ cd 4enki.com
$ git init
$ git add .
$ git commit -m "my first commit"
$ git remote add origin https://github.com/ysdyt/4enki.com.git
$ git push -u origin master
これで remoteレポジトリのmasterへpush完了
次に、GitHub上のSettingsタブから、以下のようにGitHub Pages の sourceをmaster branchからmaster branch/docs folderに選択する。
（補足）上記までの方法は、実際にwebページとして公開されるdocsフォルダ以下のファイルに限らず、hugoファイル全体をmasterブランチに公開する方法であるが、もしも 「docsフォルダのみをGitHubに公開し、それ以外のhugoファイルは公開したくない」という場合は gh-pages ブランチを使った別の方法もあるため、公式のやり方を参照のこと。
ここまで終わって、数分待ってから反映が終わっていると、https://ysdyt.github.io/4enki.com/ にページが表示されている。
（※ GitHuB Pagesで公開されるURLはいつも見慣れた github.com/ysdyt という形ではなく、ysdyt.github.ioというURLの形式になるため注意）
カスタムドメインの適応
事前にお名前.comなどでドメインを取得していることが前提となります。（スタードメインで取得した場合は以前に書いたこちらが参考になるかも）
ここでは4enki.com（年間で1000円ちょっと）というドメインを事前に取得していたため、それを先程作ったGithub Pagesに適応します。つまり、
https://ysdyt.github.io/4enki.com/portfolio/ のURLにアクセスしてきた人は https://4enki.com にリダイレクトするようにします。
お名前.comのDNSレコードを設定する
こちらのブログが画像つきでわかりやすいのでこちらの手順に従って作業
他にもいろいろブログを見てみると、お名前.com上でCNAMEを追加する方法とAレコードを追加する方法の2つあり、どちらでもいいそうなのですが、自分はCNAMEを追加する方法はうまく行かなかったのでAレコード設定のほうにしました。
GitHub側の公開設定
４つのAレコードの設定が完了したら、GitHubのsettingsタブから Custom domainに取得したドメインを指定してsave。反映が完了する時間はマチマチ（自分は10minで完了したときもあるし2時間くらい掛かったときもありました）なので気長に待ちましょう。
Aレコードを設定した場合は、CNAMEファイルの設置も不要のようです。
しばらくして見に行くと、緑でチェックマークが付きサイトへのアクセスが可能になっています。ついでの一番下にある Enforce HTTPSもチェックして、https化しましょう。
ちなみに、config.tomlファイルの baseurl = のところは、github pages urlの "https://ysdyt.github.io/4enki.com/" でも、独自ドメインの "https://4enki.com/" でもどちらでも良いようです。（前者URLを指定しても自動でリダイレクトされ後者URLに飛ばされるため）
これで完了です。
終わり
参考
- https://qiita.com/peaceiris/items/ef38cc2a4b5565d0dd7c
- https://qiita.com/satzz/items/e24bd703fc04fb45f7ef
- https://dev.to/mshr_h/hugo-github-pages-35me
- https://qiita.com/yotsak83/items/017734d5f873f4f194d4
- https://gohugo.io/content-management/shortcodes/ Hugoの記事内にyoutubeやツイッターなどを埋め込みたい場合はshortcodesというhugoオリジナルの記法を使います。
- https://gohugo.io/templates/shortcode-templates/ shortcodesに設定されていないサービスのページを埋め込みたい場合は独自に設定もできます
-
https://maku77.github.io/hugo/misc/page-bundle.html ページに画像を貼る時、画像を
static/img以下におかず、index.mdと同じ階層に管理することができます。