Hugo初心者がテーマを自作した記録 最初の一歩

2019-07-08 |
2019-11-02

The Hugo Gopher is designed by Renée French


Hugoでブログを作るのであれば、既に作成されたテーマを利用したり、それをもとにカスタマイズしたりするのがお手軽です。

しかし、自分はHTML、CSS、JSの勉強になればいいな、とテーマを自作したいと思っていました。

このように、どうせ使うのだったら自分で作ってみたいと思われた方に向けて、自分がテーマを作るために試行錯誤した記録を書いていきます。

Hugoの機能を詳細に説明するというよりかは、とりあえず動かしてみるという方針で書いていきます。

今回は、Hugoの機能でテーマを作成して、そのテーマにブログで必要そうな最低限の機能をつけてみようと思います。

Hugoでテーマを作成する

Hugoでテーマを作る方法は、Hugoのサイトが入っているディレクトリで、

hugo new theme your_theme_name

このように入力してください。もちろん、your_theme_nameの部分は好きなテーマ名を入力してください。

このように入力すると、themes/以下にthemeのディレクトリが作成されます。

このような構成になっていると思います。

my-theme
    ├── LICENSE
    ├── archetypes
    │   └── default.md
    ├── layouts
    │   ├── 404.html
    │   ├── _default
    │   │   ├── baseof.html
    │   │   ├── list.html
    │   │   └── single.html
    │   ├── index.html
    │   └── partials
    │       ├── footer.html
    │       ├── head.html
    │       └── header.html
    ├── static
    │   ├── css
    │   └── js
    └── theme.toml
テーマを作成されたら、config.tomlに、theme = "your_theme_name" を追加するのを忘れないでください。
これを忘れてしまうと、Hugoがどのテーマでサイトをビルドしたらいいのかわからず、真っ白になってしまいます。

ここで、いくつかの要素について簡単に触れていきます。

layouts/index.html

このファイルはブログのトップページに適用されるhtmlファイルです。

トップページには最新記事を表示するだけなど、そこまでこだわらない場合はindex.htmlを削除して他のテンプレートを表示させたりするテーマもあります。

私はトップページに最新記事と各カテゴリの最新記事の表示をさせて、可能であれば色々表示させてみたいと思っているのでindex.htmlはそのまま使いました。

トップページに全体の最新記事と各カテゴリの最新記事を表示させたいがためにテーマ自作に踏み切りました。

layouts/_default/single.html

このファイルは記事のページに適用されるhtmlファイルです。

Hugoはmarkdownで記事を作りますので、このページではmarkdownファイルの中身を読み込んで表示させるような処理を書く必要があります。

また、様々な記事ページに適用されるので、Hugoのテンプレート構文を使って汎用的に作る必要があります。

layouts/_default/list.html

このファイルは、私のブログを例に出すと、カテゴリページなどに適用されるhtmlファイルです。

大抵の場合、そのカテゴリの記事をいくつか表示させるような感じになると思います。

テーマカスタマイズの手順

ここまでくれば、テーマを自作するための土台ができた感じになります。

ここからいろいろいじって自分好みの見た目のテーマを作成していきます。

しかし、まず最初に何をするか

私が一番困ったのは、これでした。

公式ドキュメントを見てみても、テーマに含まれる要素の使い方とか、Hugoのテンプレート構文や、テンプレート内で使える変数の説明は載っています。

しかし、肝心の何から手を付けたらいいのか、テーマ作成のチュートリアルはないので、なんとなくカスタマイズしていきました。

おおまかな手順は以下のようになりました、

  1. index.htmlをいじってみる
  2. index.htmlに記事へのリンクを表示してみる
  3. single.htmlをいじって記事を表示してみる
  4. index.htmlにセクションへのリンクを表示してみる
  5. list.htmlをいじって、section内にある記事へのリンクを表示してみる

とりあえず、ブログとして機能しそうな最低限の部分について実装していこうと思います。

またテーマのデザインについては今回は触れませんので、各自で作成したデザインのなかに今回解説するHugoの機能を盛り込んでいってください。

私はBulmaというCSSフレームワークを利用してこのブログのテーマを作成しましたので、今後それについて解説できればしていくかもしれないです。

テーマをカスタマイズしていく

index.htmlをいじってみる

自分のサイトを表示させてみて何も映らないのは寂しいですので、index.htmlに、

Hello, World!

と書いて、Hugoでサイトを出力してみます。

hugo server -D

そうすると、Hello, World!とだけ表示されたページが表示されると思います。

このように、Hugoだからといって特別なことばかりではありませんので、リラックスして続きをやっていきたいと思います。

index.htmlに記事へのリンクを表示してみる

次に、index.htmlに記事のリンクを表示してみようと思います。

hugo new posts/my-first-post.md
hugo new posts/my-second-post.md
hugo new posts/my-third-post.md
hugo new posts/my-fourth-post.md
hugo new posts/my-fifth-post.md

みたいな感じで記事を作成していってください。

それでは、index.htmlに記事へのリンクを張っていきます。

特定のURLを指定してリンクを貼るのではなくて、Hugoのテンプレート構文を利用してそれぞれの記事へのリンクを作成していきます。

index.htmlを次にようにしてみてください。

{{ range .Site.RegularPages }}
<div>
  <a href="{{ .Permalink }}">{{ .Title }}</a>
</div>
{{ end }}

このようにしてからサイトを表示させてみると、さっき作成した記事へのリンクがタテに表示されていると思います。

ここで、見慣れない構文が出てきたと思いますが、簡単に説明してみたいと思います。

range .Site.RegularPages

{{ range .Site.RegularPages }} {{ end }}でひとつのまとまりです。

.Site.RegularPagesは、このサイトの記事ページ(正確にはcontent/にある記事ページ)のコレクションです。

rangeは、.Site.RegularPagesの要素一つ一つに対して、{{ end }}までに書かれた処理を行います。

今回の記述では、.Site.RegularPagesの要素一つ一つに対して、divタグを書いて、その中にaタグでリンクを作ります。

そして、aタグのリンクの宛先は、.Permalinkを用いてrangeが操作の対象としている要素のURLを指定します。

最後に、リンクのタイトルを.Titleを用いてrangeが操作の対象としている要素のmarkdownファイルのFront Matterで指定したtitleを指定しています。

{{ .Permalink }} , {{ .Title }}のように、書き方は似ていますが、どこからその値をとってきているのかというのを意識しておく必要があります。

single.htmlをいじって記事を表示してみる

トップページに記事ページへのリンクを貼ることができましたが、実際にクリックしてみると、Page Not Foundと表示されると思います。

なぜなら、記事ページを表示するときに適用されるsingle.htmlを作成していないからです。

ここでは最低限、markdownファイルのタイトルと内容を表示することをやってみたいと思います。

theme/my-theme/layouts/_default/single.htmlをいじっていきます。

<h1>{{ .Title }}</h1>
<div>
  {{ .Content }}
</div>

このように書いて保存し、Hugoでサイトを表示してみてください。

markdownファイルのタイトルと、本文の内容が表示されていると思います。

ここで、{{ .Content }}はmarkdownファイルの本文を指しています。

index.htmlをいじってセクションへのリンクを表示してみる

Hugoはconfig.tomlのtaxosonomiesのところにカテゴリーとかタグとかを設定することで、markdownファイルをカテゴリーやタグで分類できるようになります。

また、Hugoではcontent/のmarkdownファイルについて、それが入っているディレクトリをひとつのまとまりとしてセクションとして扱います。

私は、セクションの機能を使ってファイルを管理したかったので、セクションの中に入ってる記事へのリンクを表示してみようと思います。

そのために、まずはセクションのページへのリンクを設定します。

現在、markdownファイルは、content/posts/の中に入っています。

この場合、ページの変数にそのセクションのmarkdownファイルのコレクションが設定されているセクションページへのリンクは、https://your-domain/posts/ になります。

今回はpostsセクションのページを取得してリンクを設定します。

index.htmlに次のコードを追加してください。

{{ with .Site.GetPage "/posts" }}
<a href='{{ .Permalink }}'>posts</a>
{{ end }}

with .Site.GetPage “/posts”

.Site.GetPageは指定されたページのpathを返してくれます。

ここでは、postsのセクションページである、”/posts”のpathを返してもらいます。

withはifのような働きをしてくれるので、.Site.GetPageで”/posts”のpathが取得できたときに、そのページへのリンクを作成するというふうにしてあります。

list.htmlをいじってsection内の記事へのリンクを表示してみる

セクションへのリンクをクリックしても何も表示されないと思いますが、それはセクションページに適用されるlist.htmlをまだ作成していないからです。

とてもシンプルに、そのセクションに含まれる記事へのリンクをすべて表示するようにしてみます。

list.htmlに次のコードを書いてください。

<h1>{{ .Title }}</h1>
{{ range .Pages }}
<div>
  <a href={{ .Permalink }}>{{ .Title }}</a>
</div>
{{ end }}

再び、postsセクションへのリンクをクリックすると、セクションのタイトルであるPostsとそのセクションに含まれる記事のリンクが表示されていると思います。

まとめ

Hugoのテーマを自作するために、

  • 最新記事のリンクをトップページに貼る
  • 記事の内容を表示するページを作る
  • カテゴリーページを作る

ここまでやってみました。

これ以外にも追加したい要素、パンくずリストやカテゴリー一覧などなどたくさんありますので、これらを追加するために実際にやった作業などについて解説していけたらと思います。

参考文献

.GetPage | Hugo

range | Hugo

Variables and Params | Hugo

Please share, if you like this.