PaperModのインストール

以下を参考にPaperModをインストールする。

Hugoのテーマのインストール方法にはいくつかあるが、今回はHugo Moduleを使う方法を採用する。git submoduleを使う方法と比較して、リポジトリのクローン時に明示的な初期化が不要であり、アップデートのコマンドが単純であるという利点がある。ただしGoのインストールが必要。

空のサイトを作り、PaperModをインストールしてローカルで立ち上げるコマンドは以下の通り。

# "sitorasu.github.io"と"github.com/sitorasu/sitorasu.github.io"の部分は自分の環境に合わせて置き換える
$ hugo new site sitorasu.github.io --format yaml
$ cd sitorasu.github.io
$ hugo mod init github.com/sitorasu/sitorasu.github.io
$ cat << EOS >> hugo.yaml
module:
  imports:
  - path: github.com/adityatelange/hugo-PaperMod
EOS
$ hugo server

hugo serverで立ち上げたサイトを確認すると、PaperModのテーマが表示されているはず。

PaperMod Wikiの説明にはhugo.yamlにtheme: ["PaperMod"]を追加するよう指示があるが、Hugo Moduleを使う場合には追加してはいけない。追加するとhugo server実行時にfailed to load modules: module “PaperMod” not foundというエラーが出る。

テーマをアップデートするには以下のコマンドを実行する。

$ hugo mod get -u

Hugo Moduleの依存関係はプロジェクトのルートのgo.modというファイルに記録されており、上記コマンドで更新される。go.modはhugo mod init実行時に作成される。

設定ファイルの記述

設定ファイルはプロジェクトのルートのhugo.yaml。exampleSiteのconfig.ymlに主要な設定が載っている。意味が分からないものについてはPaperMod WikiまたはHugo Docsを参照する。だいたいデフォルトで適切な設定になっているはずなので、デフォルトで気に入らない部分だけ明示的に設定する。

アイコンの追加

ソーシャルアイコンにVRChatっぽいアイコンを追加する。svg.htmlをlayouts/partials/にコピーし、独自のSVGを追加すればよい。例えばこのコミットが参考になる。

CSSの上書き

FAQs · adityatelange/hugo-PaperMod Wikiによれば、assets/css/extendedに配置したcssはすべて読み込まれるらしい。実際にやってみたらちゃんと読み込まれた。

コードブロックのフォントがmonospaceに設定されていたので調整した。

リンクを新しいタブで開くようにする

このコメントを参考に設定。themesの下にファイルを作るのではなくプロジェクトのルート直下のlayoutsの下に作るようにした。無事成功。

最終更新日をヘッダに表示する

このプルリクエストの通りに設定する。作成日と同日中の更新は表示しない仕様のつもりなんだろうけど実装にミスがある。DateFormatの指定は2006-01-02の日付でないと機能しない。

ついでに日付の前に作成日・最終更新日の文字が表示されるようにした。

投稿日と最終更新日をコミット時に自動設定する

最終更新日だけならhugo.yamlに以下を書くだけで実現できる。

enableGitInfo: true
frontmatter:
    lastmod:
    - :git

ただ、これだと新規追加のファイルも問答無用でlastmodがついてしまって小回りが利かなかったので、Git Hooksのpre-commitで同じ仕組みを自作することにした。仕様は以下。

  • ステージングされた.mdファイルのうち、content/postsディレクトリの下にあるものを処理の対象とする
  • 変更の種別がファイルの新規追加である.mdファイルについて
    • フロントマターにdate:で始まる行がなければdate: <現在の日時>を追加する
    • フロントマターにdate:で始まる行があれば何もしない
  • 変更の種別が既存ファイルの変更である.mdファイルについて
    • フロントマターにlastmod:で始まる行があればその行を削除する
    • フロントマターにlastmod: <現在の日時>を追加する

なお、pre-commitのスクリプトは

  • .git/hooks/pre-commitに記述するか、
  • スクリプトを記述したpre-commitファイルを任意の場所に配置し、git config --local core.hooksPath <pre-commitの親ディレクトリのパス>を実行する

ことでしか機能しない。いずれにしてもクローンしてすぐに機能させることはできないので初期設定が必要になる。

Gistのサポート

そのままでは以下の警告が出るので言われたとおりに対策する。

WARN The “gist” shortcode was deprecated in v0.143.0 and will be removed in a future release. See https://gohugo.io/shortcodes/gist for instructions to create a replacement.

このコードを丸ごとコピペしてくださいというコードの中に警告のロジックが入っているのでそれは取り除かないと警告が消えないことに注意。

GitHub Actionsの登録

Host on GitHub Pagesをそのまんまやる

ファビコン・Twitterカードの設定

設定ファイルの以下のフィールドで設定する。

params:
    # Twitterカードのパス。この例ではstatic/card/logo.pngに配置する。
    images: ["/card/logo.png"]

    # ファビコンのパス。この例ではstatic/favicon.icoに配置する。
    assets:
        favicon: '/favicon.ico'

staticではなくassetsの下に配置した画像も参照できるかもしれないが、自分の環境ではうまくいかなかった。でもPaperModのサンプルサイトではassetsの下に置いてうまくいっている。謎。

TODO: 目次をリッチにする

サイドバーで追従するやつにしたい。