備忘録的なもの

Hugo のテーマを自作のものに切り替えた

Hugo のテーマを自作してそれに切り替えたので、テーマ作って切り替えるまでを一通りやった感想など。

以前 Hugoのテーマ自作するぞという記事 を書いてからだいぶ時間が空いてしまったが、 一応テーマを作って切り替える所までこぎつけることができた。

最初は知見などをまとめるつもりだったのだが、今の所 Hugo のドキュメントに書いてあることを理解する以外でそれほど詰まってはなく、 知見という形でまとめられそうに無かったので感想の形でまとめる。

作ったもの

作ったものは GitHub に置いている。

goshida/hugo-theme

ファイルとしてはこんな感じで、そんなに凝った作りでは無いと思う。

❯ tree --charset unicode themes/hugo-theme/
themes/hugo-theme/
|-- LICENSE
|-- README.md
|-- archetypes
|   `-- default.md
|-- layouts
|   |-- 404.html
|   |-- _default
|   |   |-- baseof.html
|   |   |-- list.html
|   |   |-- single.html
|   |   |-- sitemap.xml
|   |   `-- terms.html
|   |-- index.html
|   |-- partials
|   |   |-- footer.html
|   |   |-- head.html
|   |   `-- header.html
|   `-- robots.txt
|-- static
|   |-- css
|   |   |-- custom.css
|   |   `-- style.css
|   `-- images
|       |-- icon_calendar.svg
|       |-- icon_folder.svg
|       |-- icon_reload.svg
|       `-- icon_tag.svg
`-- theme.toml

デザインに関してはサイト見たら分かる通りという感じだが、今後またテーマ弄ったときのために画像で貼り付けておく

トップページの画面キャプチャ
トップページ
記事リストページの画面キャプチャ
記事リストページ
個別記事ページの画面キャプチャ
個別記事ページ

元々使っていたテーマ（ Mainroad ）で不満だった記事本文部分の幅が狭いとか、見出しの階層がわかりにくいとかも解消した。 デザインが今風かどうかは置いといて、個人的には見やすいと感じていて結構気に入っている。

あと javascript も使ってないし静的サイトという事情もあるので当然なのかもしれないが、 PageSpeed Insights でも良い点数出てくれて、こういうのは意外と嬉しい。

PageSpeed Insights 評価の画面キャプチャ
PageSpeed Insghts での評価（キャプチャは省略するがモバイルも同じ点数）

進め方についての反省点

作り始めた時点で HTML, CSS の理解が怪しかったり、 Hugo の文法とか変数とか関数も調べつつで、もう忘れてしまったこともある気はするのだが、 ああしとけばよかったこうしとけばよかったみたいな部分で印象に残っている部分をいくつかピックアップ。

ちなみに Hugo 固有のものよりは、HTML と CSS での記憶の方が強い。 Hugo に関してはとりあえず テンプレートのルックアップの仕組みだけ理解して、後はドキュメントで Variable と Function を都度調べる感じでなんとかなっている。 そもそもの理解が足りてなくて、まだああしてれば良かったこうしてれば良かったみたいなことを考える段階に居ないのかもしれない。

テスト用のサイトについて

既にこのブログでいくつか記事を書いているので、そのリポジトリでブランチ切って作っていくでも良い気はしたが、 別のテーマ用に行っている設定とごっちゃになって何かにハマりそうな気がしたため一旦公式サンプルサイトを使うことにした。

以前の記事 で書いたとおり、 Hugo のサンプルサイトで表示を確認しながらテーマを作っていったのだが、 途中で試しに既存のサイトに当てて見た所、サンプルサイト使って最後まで作り切るのは若干微妙そうなことに気付いた。

  • サンプルサイトにも Markdown 記法の確認ページはあるが、自分の使っている表現を全部網羅してるわけではない
    • 自作 shortcode の表示なども確認できない
  • サンプルサイトの確認ページで問題なくても実際は表示が崩れる場合（自作 CSS の誤りに気付かない可能性）がある
    • 1行が超長いコードブロックではみ出た部分の表示とか
    • 要素の中に要素を入れた場合（引用の中にテーブル入れたり）にどうなるかとか
  • サンプルサイト内の記事数が多くない（5ページ）関係でページングの動作の確認がしにくい
  • サンプルサイトだと英語だけだが、日本語だと結構印象が変わるので、自サイトに当てる前に CSS の再調整が必要になる

また、実際の所テンプレート書いていく中でサイトの設定（ config.toml ）がどう使われるか理解できるので、 別のテーマ用の設定が混ざってた所で変なハマり方することはなさそうと思ったのもある。

途中からはサンプルサイトは使わず、今のサイトのコンテンツで動作確認しながら進めていた。

後から考えるとという話ではあるが、最初から今のサイトのコンテンツで確認しながらテーマ作っていっても良かったなと思う。

HTML のシンタックス

最初にガリガリ書いてる最中は Hugo のローカルサーバを起動してブラウザで見ながら、 「ちゃんと見えてるな、ヨシ」で作業してたのだが、切り替えてから W3C の評価ツールを通してみると色々出ていた。

具体的にどういうエラーが出ていたか記録してないのだが、 記憶に残ってるのは <dl> タグ内で <div> タグを使う際の制限。

こんな感じで <div> タグ一個なら問題ないのだが、

<dl>
  <div>
    <dt>hoge</dt>
    <dd>fuga</dd>
  </div>
</dl>

こんな感じでもう一個間に挟むと HTML 的には Invalid だった。

<dl>
  <div>
    <div>
      <dt>hoge</dt>
      <dd>fuga</dd>
    </div>
  </div>
</dl>

ただブラウザ上だと普通に表示されてしまうこともあり、 Invalid であることに気付かず進めてしまっていて、実際に自作テーマでサイトをデプロイして評価ツールをかましたタイミングで気付いた。

後者の前提で（レスポンシブル的な変形含め） CSS も結構書いてしまっていたので、修正に結構手間取った。

普段からサイト作っている人だと当たり前なのかもしれないが、ちゃんと早い段階から評価ツールで確認しながら作っていけばよかったなと思う。

機種依存の表示崩れのデバッグ

最初にテンプレートや CSS をイチからガリガリ書いてる最中の確認は前述の通りブラウザで見ていたが、環境としては GoogleChrome (Linux) でやっていた。

で、モバイル表示の確認も開発者ツールのモバイル表示機能を使ってやっていたのだが、 こっちでもいざ切り替えて iPhone で見てみるとコードブロックの表示が崩れるという状態になっていた。

iPhone でコードブロックの表示が崩れている画像
iPhone でコードブロックの表示が崩れている様子（上が SE2 で 下が 13mini）

以前書いたある記事 のコードブロックの表示だが、 1つのコードブロック内でフォントサイズがバラバラになっている。

Chrome(Linux) でも Firefox(Linux) でも Chrome(Android) でも問題なくて、 Safari(iOS) や Chrome(iOS) でだけ崩れる。 しかも端末によってで崩れ方が違うというよくわからない状態になっていた。

Mac が手元に無いので開発者ツールとかも使えなくてどうなってるのかがさっぱり分からず、フォントやフォントサイズを意図しない所から継承してきてるのか、 シンタックスハイライトで挿入された span タグと自前 CSS が何か干渉してるのか、とか色々試して解消までに結構な時間を使った。

最終的には CSS で body タグに -webkit-text-size-adjust: 100% の1行を足すことで解消したのだが、 MDN とかで説明読んでも未だになんでこういう崩れかたしたのかや、なんでこの1行で解消したのかは理解できてない。

こういう機種依存の問題をちゃんと把握して、簡単に崩れないサイトを作っている 世の Web フロントエンジニア（デザイナー？）は偉大というのを感じた。

ちなみにこの時に色々試す中で、 --bind と --baseURL を指定することで別端末からアクセスできる形で Hugo の server を起動できるのを知ったのだが、 これ知ってれば切り替える前に気付けてたかもなと思う。

hugo server --bind 192.168.0.1 --baseURL=http://192.168.0.1

やり残したこと

切り替えに際しては、満足行くまで弄ってると無限に弄りたい部分が出てきて、 このままだといつまで経っても切り替えられないと感じたのである程度切りの良いタイミングで覚悟決めて切り替えた所がある。

そのためやりたいことは色々積んだままになっていて、今時点で思っていることとしてもこれくらいある。

  • Google Analytics 対応
  • サイト内検索フォーム
  • SNS リンクアイコン
    • とりあえず GitHub あたりから
  • サイトメニューのモバイルサイトっぽいデザイン
    • ハンバーガーボタンクリックしたらメニューが出てくるような奴
  • モバイル表示での目次の表示方法
    • PC表示だと目次をスクロールに追従する様にしているが、モバイル表示だと良い感じのデザインが思いつかず記事上部に固定する感じになっている
  • 個別記事ページでの別記事へのリンク
    • 前に書いた記事、次に書いた記事、最近書いた記事、（どうやるのがイメージ付いてないけど）関連記事あたり、のどれか
  • ホームページのデザイン
    • 何か画像ドーンと置いてみたいなのやりたかったが、良い感じのものが思いつかなかったのでサブコンテンツにするつもりだった直近10件の記事リストだけになってる
  • 縦並び横並びで Flexbox を使いすぎた感あり、若干弄りにくさ出てきたのでその辺の整理
  • 表示するタクソノミーとして tags と category をテンプレートにベタ書きしてるのでその辺の修正
  • 公式テーマの申請
    • README とか theme.toml とか諸々の整備
    • リポジトリ名もなんとかする必要ある

最終的には公式テーマとして申請したいとは思ってるものの、既存のテーマに比べると機能的に明らかに足りない感があるので、 その辺の充実が先かなとは思っている。

作業を通しての感想

テーマを切り替えてデプロイするまでの作業をやった全体的な感想としてはこんな感じ

  • HTML, CSS を弄って自分好みにデザインしていくのは何やかんや楽しい
  • Hugo のドキュメントとにらめっこしながら色々思考錯誤してテンプレート書くのもそれなりに楽しい
  • PageSpeed Insights とか評価ツールを回して改善していくのもサイト運営してる感があるので良い
  • 作り始めると意外とやりたいことも色々出てくる

総じて時間が溶けることを考慮しなければ楽しめている。 仕事みたいに期限が無いことや、趣味の個人サイトなので多少ミスってもそこまでダメージ無いというのも楽しめている要因だろうという気もする。

やり残したことは時間のあるタイミングでぼちぼちやっていければと良いなと思う。