Hugoでブログを構築した(HugoセットアップからGitHubにgit pushするまで)

Hugoでブログを構築した(HugoセットアップからGitHubにgit pushするまで)
Page content

色々思うところがあって、Hugoでブログを構築することに決めた。今までははてなブログに少しだけ記事を投稿していたけれど、どうせなら1から作ってみようと思ったのだった。

想定環境

$ sw_vers
ProductName:	Mac OS X
ProductVersion:	10.15.6  # catalina
BuildVersion:	19G73

$ brew -v
Homebrew 2.4.9
Homebrew/homebrew-core (git revision edab7; last commit 2020-08-04)
Homebrew/homebrew-cask (git revision 8677d; last commit 2020-08-04)

$ git --version
git version 2.27.0
  • GitHubのアカウントは取得済み かつ 基本的な操作は把握済み

Hugoのインストール

macOSを利用している開発者だと高確率で Homebrew を利用されているかと思うので、Hugoのインストールもこれを用いて行う。

$ brew install hugo
$ hugo version
Hugo Static Site Generator v0.74.2/extended darwin/amd64 BuildDate: unknown

他の環境を利用されている方は以下を参照のこと。

Hugoでサイトの雛形をローカルに構築する

以下からは、フォルダやプロジェクト名に使う文字列として klim0824 を用いることにする。

$ hugo new site klim0824

これを叩くことによって、 klim0824 ディレクトリが生成され、そのディレクトリ内に雛形が生成される。 すでにプロジェクト名のディレクトリを作成済み & そのディレクトリ内に移動している場合は以下のように . を用いる。

$ hugo new site .

hugo new site を叩くと、以下のようにファイルが生成される。

$ cd klim0824 
$ tree  # カレントディレクトリ以下の階層を表示してくれる。 brew install tree でインストール。
.
├── archetypes
│   └── default.md
├── config.toml
├── content
├── data
├── layouts
├── static
└── themes
$ cat archetypes/default.md
---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: true
---

$ cat config.toml
baseURL = "http://example.org/"
languageCode = "en-us"
title = "My New Hugo Site"

archetypes/default.md は記事の作成時に反映されるテンプレートで、config.toml はサイト全体の設定を行うためのファイル。 これだけだと何もないも同然なので、記事の作成とテーマ設定を行う。まずはテーマから。

Hugoのテーマを適用する

今回はMainroadというテーマを適用することにした。

基本的に themes/[テーマ名] ディレクトリを作成し、その中にテーマのファイルを配置する流れになるが、単に git clone するだけだと、サイトの設定や記事をGitで管理する時にそのテーマ自体も配下に含まれてしまう。 できるなら git submodule を活用して、サイト本体の管理とテーマの管理を分離しておきたい。こうすることで、テーマはテーマの配信元で管理されるようになり、自らがわざわざ管理する必要はなくなる。

という訳で、叩くコマンドは以下のとおり。 git submodule を叩く際、レポジトリのURLの次に保存先のディレクトリ名(今回は themes/mainroad)を指定するのをお忘れなく。

$ git init
$ git submodule add https://github.com/Vimux/Mainroad.git themes/mainroad

すると以下のようなファイル構成になる(見やすさのため、3階層目まで表示)。

$ tree -a -L 3  # -aは隠しファイルやディレクトリも表示させるオプション。-L 3は3階層目まで表示するオプション。
.
├── .git
│   └ 省略
├── .gitmodules
├── archetypes
│   └── default.md
├── config.toml
├── content
├── data
├── layouts
├── static
└── themes
    └── mainroad
        ├── CONTRIBUTING.md
        ├── LICENSE.md
        ├── README.md
        ├── archetypes
        ├── assets
        ├── exampleSite
        ├── i18n
        ├── images
        ├── layouts
        ├── package-lock.json
        ├── package.json
        ├── static
        └── theme.toml

ここまで来たら、次に config.toml にテーマを指定する記述を追加する(4行目)。値には themes ディレクトリ配下のディレクトリ名を用いる。

ついでに、 languageCode を日本語対応に、 title にはサイト名を設定する。

baseURL = "http://example.org/"
languageCode = "ja"
title = "klim0824.log()"
theme = "mainroad"

config.toml に様々な設定を追加・編集することになるが、今は一旦先に進める。1

記事を追加する

記事を追加するには hugo new を叩く。

$ hugo new post/sample/index.md

すると、 content ディレクトリ配下に post/sample/index.md が生成されている。

$ tree -a -L 3
.
├── .git
│   └ 省略
├── .gitmodules
├── archetypes
│   └── default.md
├── config.toml
├── content
│   └── post
│       └── sample
│          └── index.md   ←ココ!
├── data
├── layouts
├── resources             ←ココも追加されているけれど今回はスルーで
│   └── _gen
│       ├── assets
│       └── images
├── static
└── themes
    └── mainroad
        └── 省略

生成された post/sample/index.md の中身はこちら。 $ cat archetypes/default.md の中身と対応していることがお分かり頂けると思う。

---
title: "Sample"
date: 2020-08-01T21:41:24+09:00
draft: true
---

draft の箇所は下書きの意味。ここを false にするか、1行丸々削除すると本公開用の記事になる。 以下のように記事を書いていく。少なくともMainroadテーマでは title がHTML上の <h1> に相当するので、記事内の見出しはHTMLの <h2> 相当である ## から始めると良い。

---
title: "Hugo+GitHub+Netifyでブログを構築した(HugoセットアップからGitHubにgit pushするまで)"
date: 2020-08-01T20:12:07+09:00
draft: false
---

## 環境

- macOS Catalina
- Homebrew 2.4.9
- Git 2.27.0

## Hugoのインストール

​```bash
$ brew install hugo
$ hugo version
Hugo Static Site Generator v0.74.2/extended darwin/amd64 BuildDate: unknown
​```

## Hugoでサイトの雛形をローカルに構築する

以下からは、フォルダやプロジェクト名に使う文字列として `klim0824` を用いることにする。
.
.
.

ローカルサーバーを立ち上げてプレビューする

ここまで来たらいよいよブラウザで表示を確認できる。

$ hugo server 

draft: true で下書き設定している記事もプレビューしたい場合は -D オプションを付ける。

$ hugo server -D

コマンドを叩くと以下のように表示される。

$ hugo server -D

# ここにWARNが表示されるけど今回はスルーで

                   | EN  
-------------------+-----
  Pages            |  4  
  Paginator pages  |  0  
  Non-page files   |  0  
  Static files     |  0  
  Processed images |  0  
  Aliases          |  0  
  Sitemaps         |  1  
  Cleaned          |  0  

Built in 5 ms
Watching for changes in /Users/USER/projectpath/klim0824/{archetypes,content,data,layouts,static}
Watching for config changes in /Users/USER/projectpath/klim0824/config.toml
Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop


この状態で http://localhost:1313/ にアクセスすると以下のような感じに表示される。

  • TOP(http://localhost:1313/)

    • top
  • 記事(http://localhost:1313/post/sample/)

    • article

やったぜ!

Githibにレポジトリを作成 & git push

GitHubにリポジトリを作成する具体的な方法は割愛。ここではリポジトリを作成し終わって、 git@github.com:klim0824/klim0824.git というURLを生成したという体で話を進める。

これまでの作業を git commit しておく(テーマをcloneした時点で git init しているため、すんなりgitコマンドが通るようになっている)。そして、 git remote add origin でリモートリポジトリを登録しておき、最後は git push する。

$ git add .
$ git commit -m "Initial Commit"
$ git remote add origin git@github.com:klim0824/klim0824.git
$ git push origin master

感想

思いの外簡単にサイト構築が進められて大変DX(開発体験)が高くて素晴らしい! 一方で、自由度が比較的高い仕様ということもあり、導入するテーマによって設定箇所やその作法が大きく異なるようにも感じた。今回はMainroadというテーマを選んでこの記事を書いたが、これ以前に様々なテーマを選択して試行錯誤していた(中には記事やテーマを表示するところまで行けなかったテーマもあった)。ここらへんは単純になれの問題なのかもしれない。

ご覧の通り、Mainroadというテーマを使ってこのブログも構築することにしているが、まだまだ設定が甘いと感じている。8月中にはサマになるようなUIを目指したい。

todo

  • config.toml を鍛える
  • HTML/CSS/JavaScriptを追加・編集する
  • GitHubとNetlifyへの連携
  • NetlifyとSlackをIFTTT経由で無料で連携
  • はてなブログからいくつか記事をインポート

参考URL


  1. 筆者はVisual Studio Codeでソースを編集しているが、.tomlファイルのシンタックスハイライトにはBetter TOMLを利用している。 ↩︎