Hugo + GitHub Pagesでのサイト構築例１（研究室用サイト） #GithubPages

＊＊＊　備忘録です。間違い等があればご指摘ください。　＊＊＊

概要

Hugoを用いて研究室用サイトを構築し、GitHub Pagesで公開する。（個人用サイトの例はこちら。）
HugoのテーマはBlackburnを用いる。（その他のテーマはこちら。)
URLはhttps://ユーザー名.github.ioとする。（https://ユーザー名.github.io/リポジトリ名ではなく。詳細はこちらを参照。）
リポジトリ名はユーザー名.github.ioとする。
アイコン等はFont Awesome 4.7を用いる。

前提

GitHubのSign up（ユーザー登録）は終了している。
SSH公開鍵の作成とGitHubへの登録は終了している。

GitHubにリモートリポジトリを作成する

リモートリポジトリユーザー名Siteを作成する。

https://github.com/にSign inする。
右上の「+」から「New repository」を選択する。
「Repository name」にユーザー名Siteを入力する。
~~リポジトリを公開する場合は「Public」、公開しない場合は「Private」をチェックする。~~　有償版のGitHubを使用している場合は「Public」（リポジトリを公開する）あるいは「Private」（リポジトリを公開しない）をチェックする。無償版を使用している場合は「Public」を選択する。
「Initialize this repository with a README」をチェックする。
「Add .gitignore: None」および「Add a license: None」を選択する（デフォルト）。
「Create repository」をクリックする。

同様に、リモートリポジトリユーザー名.github.ioを作成する。ただし、

ローカル環境にサイトを準備する（Hugoのプロジェクトを作成する）

Hugoをインストールする。

$ brew install hugo

Hugoのプロジェクトを作成する。

$ hugo new site ~/GitHub/ユーザー名Site/

ローカルリポジトリユーザー名Siteを作成する。

$ cd ~/GitHub/ユーザー名Site/
$ git init
$ git remote add origin https://github.com/ユーザー名/ユーザー名Site.git
$ git pull origin master

リモートリポジトリユーザー名.github.ioをsubmoduleとして登録する。

$ git submodule add https://github.com/ユーザー名/ユーザー名.github.io.git public

Hugoのテーマをsubmoduleとしてダウンロードする。

$ git submodule add https://github.com/yoshiharuyamashita/blackburn.git themes/blackburn

デフォルトのディレクトリlayoutsをテーマのものに変更する。

$ cp -R  themes/blackburn/layouts/ layouts/

デフォルトのディレクトリexampleSiteをテーマのものに変更する。

$ cp -a themes/blackburn/exampleSite/ .
overwrite ./config.toml? (y/n [n]) y  <-- 「y」を入力

ローカル環境でサイトを確認する。ターミナルで別のウインドウを開き、

$ cd ~/GitHub/ユーザー名Site/
$ hugo server -w

元のウインドウに戻り、

$ open http://localhost:1313/

ブラウザが開くので、テーマのデモとほぼ同様であるかを確認する。
以降、Hugoでファイルの変更等を行うと、このブラウザがリアルタイムで更新されるので確認する。

サイト全体の設定ファイル`config.toml`を修正する

テーマのデフォルトのconfig.tomlを以下に示すが、各サイトに合わせて修正する。

baseurl = "https://www.example.com/"  <-- 公開するURLに変更（最後の「/」を付け忘れると、スマホでメニューが開かなくなるので要注意）
languageCode = "en-us"  <-- 日本語サイトであればjaに変更
title = "Blackburn Theme Demo"  <-- 公開するサイト名に変更
theme = "blackburn"
author = "Yoshiharu Yamashita"  <-- サイトの作成者に変更
copyright = "&copy; 2016. All rights reserved."  <-- 公開する年に変更
canonifyurls = true
paginate = 10
hasCJKLanguage = true  <-- デフォルトにはないが追加（日本語の記事のサマリーが長くなることを防ぐ）

[indexes]
  tag = "tags"
  topic = "topics"

[params]
  # Shown in the home page
  subtitle = "A Hugo Theme"  <-- 公開するサブタイトルに変更、不要であればコメントアウト
  brand = "Blackburn"  <-- 左メニューの上部に表示するタイトルに変更
  googleAnalytics = "Your Google Analytics tracking ID"  <--Google Analyticsを使用していなければコメントアウト
  disqus = "Your Disqus shortname"  <-- Disqusを使用していなければコメントアウト
  # CSS name for highlight.js
  highlightjs = "androidstudio"
  dateFormat = "02 Jan 2006, 15:04"  <-- 日時の表示形式を変更

[menu]
  # Shown in the side menu.
  [[menu.main]]  <-- 左メニューに表示する項目、必要に応じて変更あるいは削除
    name = "Home"
    pre = "<i class='fa fa-home fa-fw'></I>"  <-- アイコン
    weight = 1  <-- 表示する順序
    identifier = "home"  <-- 表示する名称
    url = "/"
  [[menu.main]]
    name = "Posts"
    pre = "<i class='fa fa-list fa-fw'></i>"
    weight = 2
    identifier = "post"
    url = "/post/"
  [[menu.main]]
    name = "About"
    pre = "<i class='fa fa-user fa-fw'></i>"
    weight = 3
    identifier = "about"
    url = "/about/"  <-- 固定ページ用ファイルの作成位置
  [[menu.main]]
    name = "Contact"
    pre = "<i class='fa fa-phone fa-fw'></i>"
    weight = 4
    url = "/contact/"

[social]
  # Link your social networking accouns to the side menu
  # by entering your username or ID.
  twitter = "*"  <-- ユーザー名を入力、不要であればコメントアウト
  facebook = "*"  <-- ユーザー名を入力、不要であればコメントアウト
  instagram = "*"  <-- ユーザー名を入力、不要であればコメントアウト
  github = "yoshiharuyamashita"
  stackoverflow = "*"  <-- ユーザー名を入力、不要であればコメントアウト
  linkedin = "*"  <-- ユーザー名を入力、不要であればコメントアウト

修正されたconfig.tomlの例を以下に示す。

baseurl = "https://xxxxx.github.io/"
languageCode = "en-us"
title = "Momotaro Lab"
theme = "blackburn"
author = "Momotaro"
copyright = "&copy; 2019. All rights reserved."
canonifyurls = true
paginate = 10
hasCJKLanguage = true

[indexes]
  tag = "tags"
  topic = "topics"

[params]
  # Shown in the home page
  subtitle = "Faculty of Old Tales, Legend University"
  brand = "Momotaro Lab"
  googleAnalytics = "UA-123-45"
  # disqus = "Your Disqus shortname"
  # CSS name for highlight.js
  highlightjs = "androidstudio"
  dateFormat = "02 Jan 2006"

[menu]
  # Shown in the side menu.
  [[menu.main]]
    name = "Home"
    pre = "<i class='fa fa-home fa-fw'></i>"
    weight = 1
    identifier = "home"
    url = "/"
  [[menu.main]]
    name = "About"
    pre = "<i class='fa fa-info-circle fa-fw'></i>"
    weight = 2
    identifier = "about"
    url = "/page/about/"
  [[menu.main]]
    name = "Taggers"
    pre = "<i class='fa fa-globe fa-fw'></i>"
    weight = 3
    identifier = "taggers"
    url = "/page/taggers/"
  [[menu.main]]
    name = "Research"
    pre = "<i class='fa fa-bar-chart fa-fw'></i>"
    # pre = "<i class='fa fa-flask fa-fw'></i>"
    weight = 4
    identifier = "research"
    url = "/page/research/"
  [[menu.main]]
    name = "Publications"
    pre = "<i class='fa fa-book fa-fw'></i>"
    weight = 5
    identifier = "publications"
    url = "/page/publications/"
  [[menu.main]]
    name = "People"
    pre = "<i class='fa fa-user fa-fw'></i>"
    weight = 6
    identifier = "people"
    url = "/page/people/"
  [[menu.main]]
    name = "Computing"
    pre = "<i class='fa fa-desktop fa-fw'></i>"
    weight = 7
    identifier = "computing"
    url = "/page/computing/"
  [[menu.main]]
    name = "For students"
    pre = "<i class='fa fa-graduation-cap fa-fw'></i>"
    weight = 8
    identifier = "forstudents"
    url = "/page/forstudents/"
  [[menu.main]]
    name = "Access"
    pre = "<i class='fa fa-subway fa-fw'></i>"
    weight = 9
    identifier = "access"
    url = "/page/access/"
  [[menu.main]]
    name = "Contact"
    pre = "<i class='fa fa-envelope fa-fw'></i>"
    weight = 10
    identifier = "contact"
    url = "/page/contact/"
  [[menu.main]]
    name = "Link"
    pre = "<i class='fa fa-external-link fa-fw'></i>"
    weight = 11
    identifier = "link"
    url = "/page/link/"

[social]
  # Link your social networking accouns to the side menu
  # by entering your username or ID.
  # twitter = "*"
  # facebook = "*"
  # instagram = "*"
  github = "xxxxx"
  # stackoverflow = "*"
  # linkedin = "*"

固定ページを作成する

固定ページを保存するディレクトリpageを作成する。

$ mkdir content/page

テーマから複製した固定ページを移動する。

$ cd content/
$ mv *.md page

about.mdなどを参考にして、以下の様に必要な固定ページを作成する。

$ cd page/
$ vi about.md
+++
title = "About Momotaro Lab"  <-- 公開する固定ページのタイトルに変更
date = "2019-07-10"  <-- 必要に応じて変更
sidemenu = "true"  <-- 公開する場合はfalseに修正
description = ""
+++  <-- これより下にマークダウンで内容を入力
<div style="text-align: center;">
<h1>Sorry, Under constraction!</h1>
<i class="fa fa-wrench fa-5x"></i>
</div>
$ vi ...

記事（post）を作成する

テスト用にテーマから複製した記事を削除する。

$ rm -rf content/post/*

テーマの記事を参考にして、以下の様に記事を作成する。なお、テーマの記事はthemes/blackburn/exampleSite/content/post/にある。

$ cd ../..
$ hugo new post/post名.md
$ vi content/post/post名.md
+++
title = "post名"  <-- 公開する記事のタイトルに変更
date = "2019-07-10T13:57:52+09:00"  <-- 必要に応じて変更
draft = true  <-- 公開する場合はfalseに修正
tags = []  <-- 必要に応じて入力
topics = []  <-- 必要に応じて入力
description = ""  <-- 必要に応じて入力
+++  <-- これより下にマークダウンで内容を入力

公開用サイトを作成し、アップロードする

公開用サイトを作成する。

$ hugo

リモートリポジトリユーザー名.github.ioを更新する。

$ cd public/
$ git add -A
$ git commit -m "Make site by Hugo"
# git push

GitHub Pagesを確認する。

$ open https://ユーザー名.github.io

Hugoのプロジェクトをリモートリポジトリ`ユーザー名Site`へ登録する

$ cd ..
$ git add -A
$ git commit -m "Make Hugo project"
$ git push -u origin master

サイトを更新する

以降、サイトの設定、固定ページや記事の作成・修正・削除等を行った場合は、サイトを確認し、リモートリポジトリを更新する。

$ cd ~/GitHub/ユーザー名Site/
$ hugo server -w  <-- ターミナルの別のウィンドウで
$ open http://localhost:1313/  <-- ローカル環境でサイトを確認
$ hugo  <-- 公開用サイトを作成
$ cd public/
$ git add -A
$ git commit -m "コメント"
# git push  <-- リモートリポジトリ ユーザー名.github.ioに登録されている公開用サイトを更新
$ open https://ユーザー名.github.io  <-- GitHub Pagesを確認
$ cd ..
$ git add -A
$ git commit -m "コメント"
$ git push  <-- リモートリポジトリ ユーザー名Siteに登録されているHugoのプロジェクトを更新

備考

記事ファイルの「+++」で囲まれている部分はFront Matterと言い、ページ単位の設定を記述する領域である。
記事の表示順序を変えるときはFront Matter「weight = 数字」を記述する。数字が小さいほど上位に表示される。また、weightが設定されている記事は設定されていない記事より上位に表示される。
content/pages/にファイルを入れると以下のようなWarningが出る。

$ hugo server -w
Building sites … WARN 2019/07/15 15:36:47 found no layout file for "HTML" for "section": You should create a template file which matches Hugo Layouts Lookup Rules for this combination.

「hugo v0.51でビルドエラー」を参考にさせていただき、以下のように対処する。

$ cd ~/GitHub/ユーザー名Site/layouts/_default/
$ touch list.html

date変数は日付のみでも良い（例えば，"2019-07-10"）。しかし、タイムゾーンはUTCとなるため、日本では午前9時までは未来の投稿となりhugoコマンドではbuildされない。その場合は、未来のpostもbuildするオプション-Fを使用する。ただし、他に未来のpostがあると、それらも一緒にbuildされることに注意が必要。

$ hugo -F

追記

当初は以下のような管理を行っていたが、実際に運用してみると面倒だったので削除した。

Hugoのプロジェクトと公開用サイトは別々のリポジトリで管理する。リポジトリ名は、前者をユーザー名Site（例えば、ユーザー名がxxxxxならxxxxxSite）、後者をユーザー名.github.ioとする。後者を前者のsubmoduleとする。

Hugo + GitHub Pagesでのサイト構築例１（研究室用サイト）

概要

前提