Hugo テーマ作成STEP1
Hugo でテーマ作成をする時まずはじめにすることをまとめました。
Hugoのテーマ作成をはじめるときに、まず何から手をつけたら良いでしょうか。 私は次のような手順で作業を開始しました。
Hugo はコンテナで実行していますので、dockerをあらかじめインストールしてあります。
- Hugoの新サイトを作成する or HugoBasicExampleをcloneする
- テーマの雛形を作成する
- dockerのhugoイメージを取得する
Hugoの新サイトを作成する or HugoBasicExampleをcloneする
まずは開発したテーマを反映させるサイトを作成します。hugoで空の新サイトを作成することもできますし、ある程度のコンテンツが入っているhugoBasicExampleサイトがgithubで公開されていますのでそれを利用することもできます。
Hugoの新サイトを作成する
新サイトを作成する場合はhugo new site コマンドを利用します。ここではdocker imageを利用しますので以下のように作成します。
$ docker run --rm -it -v $(pwd):/src klakegg/hugo:0.72.0 new site hugoBasicExample
HugoBasicExampleをcloneする
HugoBasicExampleを利用する場合にはgithubからcloneします。
https://github.com/gohugoio/hugoBasicExample
git clone https://github.com/gohugoio/hugoBasicExample.git
テーマの雛形を作成する
用意したサイトのトップディレクトリで hugo new theme コマンドを使用します。
$ docker run --rm -it -v $(pwd):/src klakegg/hugo:0.72.0 new theme sample
次のような構成でテーマの雛形が作成されます。
themes/
└── sample
├── 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
サーバーを起動して表示を確認する
hugo にはHTTPサーバーを起動する機能がありますので、まずは実行してみましょう。先ほどまでと実行方法は似ていますが、HTTPサーバーへアクセスするためのポート開放のオプションがついています。
$ docker run --rm -it -v $(pwd):/src -p 1313:1313 klakegg/hugo:0.72.0 server --theme sample
| EN
-------------------+-----
Pages | 19
Paginator pages | 0
Non-page files | 0
Static files | 1
Processed images | 0
Aliases | 9
Sitemaps | 1
Cleaned | 0
Built in 1606 ms
Watching for changes in /src/{content,layouts,static,themes}
Watching for config changes in /src/config.toml
Environment: "DEV"
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 0.0.0.0)
Press Ctrl+C to stop
ブラウザでhttp://localhost:1313/ にアクセスします。まだ真っ白のページが表示されるだけですがこれでOKです。
<pre>
</pre>
ページのソースをみてもpreタグが出力されるだけです。
index.htmlを作成する
themes/sample/layouts/index.htmlを編集します。まだ空ファイルのindex.htmlに以下の２行を追記します。
{{ define "main" }}
{{ end }}
サーバーが動いている状態であれば、自動でテンプレートの修正を検知して反映してくれます。反映されない場合はサーバーを再起動しましょう。ただ、まだここでも真っ白のページは変わりません。しかしページのソースを確認すると出力が変化しました。
<!DOCTYPE html>
<html><body><div id="content">
</div><script src="/livereload.js?port=1313&mindelay=10&v=2" data-no-instant defer></script></body>
</html>
これは index.htmlの修正により、themes/sample/layouts/_default/baseof.html を参照してコンテンツが作成されたためです。
<!DOCTYPE html>
<html>
{{- partial "head.html" . -}}
<body>
{{- partial "header.html" . -}}
<div id="content">
{{- block "main" . }}{{- end }}
</div>
{{- partial "footer.html" . -}}
</body>
</html>
この時のbaseof.htmlの内容です。 block “main” と index.html の define “main” が対応して表示が変わりました。このあたりの詳細はBase Templates and Blocksを参照してください。
コンテンツ言語の設定
config.tomlの設定を参照して言語設定を行います。baseof.htmlを次のように修正しました。
<html>
↓
<html lang="{{.Site.LanguageCode}}">
ページのソースを確認するとhtmlタグに lang=en が追記されるようになりました。
mainタグへの変更
テーマの雛形では divタグ で id="content"を指定していますが、mainタグへ変更し適切なセマンティック要素を使用するようにします。ここまでの変更でbaseof.htmlは次のようになりました。
<html lang="{{.Site.LanguageCode}}">
{{- partial "head.html" . -}}
<body>
{{- partial "header.html" . -}}
<main>
{{- block "main" . }}{{- end }}
</main>
{{- partial "footer.html" . -}}
</body>
</html>
コンテンツの表示
index.htmlへ次のようにContentを表示する１行を挿入します。
{{ define "main" }}
{{ .Content }}
{{ end }}
また content/_index.md を以下のように修正します。
+++
author = "Hugo Authors"
+++
# Heading
This is sample content
保存してブラウザ確認すると内容が表示されるようになりました。なお、_（アンダースコア）付きのファイルはそのフォルダに子ページを含む別のフォルダが存在する場合に使われます（詳しくはContent Sectionsを参照してください）。
ヘッダーの調整
文字コードセット
<meta charset="utf-8">
レスポンシブ対応するためのメタ情報
<meta name="viewport" content="width=device-width, initial-scale=1.0">
タイトルの設定
<title>{{ .Site.Title }}</title>
ページタイトルはサイトで一意にする必要があります。ここではサイト変数を利用して設定しています。
サイトの情報
<meta name="description" content="{{if .IsHome}}{{ $.Site.Params.description }}{{else}}{{.Description}}{{end}}" />
desctiptionメタ情報は検索エンジンの結果ページでリンクの下に表示されるテキストです。通常は150文字未満にする必要があります。ここではホーム(サイトのトップページ)であればサイト変数のdesctiptionをホーム以外ではページに設定されているDescriptionを表示します。
サイトの説明の設定
config.tomlで指定します。
[params]
description = "My site description"
ページの説明の設定
各ページで指定します。
title: "Sample post"
date: 2020-06-21T18:00:00+09:00
description: "This is a sample description of the page"
Canonical urlを設定する
<link rel="canonical" href="{{ .Permalink }}" />
検索エンジンに重複ページのペナルティを受けないようにページ固有のURLを生成します。ここではパーマリンクを記事で設定しそれを利用するようにしています。
パーマリンクの指定方法
パーマリンクを指定するには記事のurlパラメーターを指定します。
title: "Sample post"
date: 2020-06-21T18:00:00+09:00
url: "https://uche.life/p/[ランダム文字列]"
記事固有のランダム文字列を指定します。/p/は1階層目を別用途で利用することがあるのでこうしています。
CSSの設定
CSSを読み込むため以下を追加します。
<link rel="stylesheet" href="css/style.css">
style.cssはthemes/sample/static/css/に配置します。外部のリセットCSSを直接読み込んで利用する場合には同じように設定を行います。
SNS共有用の設定
Hugoでは各SNS共有を行うためのメタデータ情報が内部テンプレート化されていますのでそれを利用します。ここではTwitterカードを利用する時の設定を行っています。
{{ template "_internal/twitter_cards.html" . }}
これで誰かがこのページをTwitterにリンクした時にFront-matterで正しく情報が設定されていれば表示されるようになります。
Google Analitics
Google Analiticsの設定も内部テンプレート化されています。
{{ template "_internal/google_analytics_async.html" . }}
googleAnalyticsの設定
Google Analiticsを有効にするためconfig.tomlに次の行を追加します。
googleAnalytics = "UA-123-45"
ここまでのhead.html
ここまで設定すると次のような head.htmlが作成できていると思います。
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="{{if .IsHome}}{{ $.Site.Params.description }}{{else}}{{.Description}}{{end}}" />
<title>{{ .Site.Title }}</title>
<link rel="canonical" href="{{ .Permalink }}" />
{{ template "_internal/twitter_cards.html" . }}
{{ template "_internal/google_analytics_async.html" . }}
</head>
その他の調整
日本語の要約生成に必要な対応
config.tomlに次の設定を行います。
hasCJKLanguage = true
デフォルトのHugoは英語などのスペースを語句の区切りに使う言語を想定しており、日本語はうまく機能しません。こちらの設定いれることで日本語でも長すぎない要約を生成します。この他に要約をユーザーの定義した位置で指定(
)する方法もあります。
まとめ
これでテーマの雛形は完成です。 次回は全体的なページのレイアウトを作成していきたいと思います。
