Docsyの適用

Hugoのテーマ「Docsy」の適用方法を紹介します。

ゴール

下記は、Hugo + GitLab Pagesによるブログ環境の構成要素です。 ここでは、GitLabのHugoテーマ/コンテンツリポジトリに含まれるテーマ本体をDocsyに変更し、テーマ設定/コンテンツをDocsyサンプルに入れ替え、CI/CD設定をDocsy向けに変更して、サンプルサイトをビルド/公開することをゴールとします。

前提

Hugo + GitLab Pagesブログサーバ」, 「VSCode開発クライアント」を実施し、GitLab Pages/Hugoテンプレートで構築されたサーバ環境とVisual Studio Codeによる開発クライアント環境がある前提で説明します。

適用方法

Visual Studio Codeでテーマ本体, テーマ設定/コンテンツを変更
  1. Visual Studio Codeで管理するHugoリポジトリ資産の/.gitlab-ci.yml以外を削除します。

  2. ブラウザでDocsyのサンプルプロジェクトを開き、すべてのファイルをダウンロードして、Visual Studio Codeで管理するHugoリポジトリ資産の/にコピーします。

    Hugoリポジトリ資産
    ├ assets            ← ダウンロードしたものをコピー
    ├ content           ← ダウンロードしたものをコピー
    ├ layouts           ← ダウンロードしたものをコピー
    ├ .gitlab-ci.yml
    ├ go.mod            ← ダウンロードしたものをコピー
    ├ go.sum            ← ダウンロードしたものをコピー
    └ hugo.toml         ← ダウンロードしたものをコピー
    

    なお、テーマ本体/themesはHugoリポジトリ資産として登録しません。 後続のCI/CD設定変更により、ビルド時に動的に取り込まれます。

  3. Visual Studio Codeで/hugo.tomlを開き、baseurlサンプルサイトのルートURLに変更します。

Visual Studio CodeでCI/CD設定をテーマに合わせて変更
  1. Visual Studio Codeで管理するHugoリポジトリ資産の/.gitlab-ci.ymlを削除します。

  2. ブラウザでGitLab Pages/Hugoテンプレートの.gitlab-ci.ymlを開き、ダウンロードして、Visual Studio Codeで管理するHugoリポジトリ資産の/にコピーします。

  3. Visual Studio Codeで/.gitlab-ci.ymlを開き、imagehugo_extendedが指定されていることを確認し、hugo mod getの対象をDocsyに変更して、npm, PostCSSのインストール記述を追加します。

    ...
    image: registry.gitlab.com/pages/hugo/hugo_extended:latest     ← 確認
    
    variables:
      HUGO_ENV: production
      THEME_URL: "github.com/google/docsy"                         ← 変更
    
    default:
      before_script:
        - apk add --no-cache go curl bash nodejs
        - hugo mod get -u $THEME_URL
        ## Uncomment the following if you use PostCSS...
        - apk add --update npm                                     ← 追加
        - npm install postcss postcss-cli autoprefixer             ← コメント除去
    ...
    
Visual Studio Codeで行った変更を、GitLabへアップロード

Visual Studio Codeで変更したHugoリポジトリ資産をGitLabへアップロード - VSCode開発クライアント」を実施します。

GitLabで自動的に行われたビルド/公開結果を確認

GitLabで自動的に行われたビルド/公開結果を確認 - VSCode開発クライアント」を実施します。

トラブルシューティング

テーマをHugo Moduleとして適用すると「Error: failed to load modules:…」が発生する

現象

テーマを、Git submodule等の方法で適用するのではなく、Hugo Moduleとして適用すると、下記エラーが発生します。

: Error: failed to load modules: module "..." not found in "..."; either add it as a Hugo Module or store it in "...".: module does not exist

原因

Hugoの何らかの変更により、GitLab CI/CDでhigo mod initするとエラーが発生するようになったようです。 詳細はGitLab Pages exaplesのIssueを参照してください。

なお、Hugo V0.109.0迄は発生しなかったことから、V0.110.0以降の変更に起因していると思われます。

対処

.gitlab-ci.ymlhigo mod initを削除し、あらかじめローカルで生成しておいたgo.mod, go.sumをリポジトリ登録します。 詳細はGitLab Pages exaplesのMerge requestを参照してください。

急ぐ場合は、.gitlab-ci.ymlでHugo V0.109.0(確実に動作していたバージョン)を指定する方法もあります。

...
image: registry.gitlab.com/pages/hugo/hugo_extended:0.109.0
...

MermaidのScriptが常にロードされる

現象

Mermaidを使用しているしていないに関わらず、常にページにMermaidのScriptがロードされ、不必要なロードコストがかかります。

<script src="https://cdn.jsdelivr.net/npm/mermaid@9.3.0/dist/mermaid.min.js" integrity="sha512-ku2nmBrzAXY5YwohzTqLYH1/lvyMrpTVxgQKrvTabd/b/uesqltLORdmpVapYv6QhZVCLUX6wkvFaKOAY4xpUA==" crossorigin="anonymous"></script>

原因

Docsy V0.7.0の仕様変更によるもの。 hugo.config[params.mermaid]の定義があるだけで、enable=falseとしていたとしても、Mermaidが有効になるようになりました。

[params.mermaid]
enable = false

詳細はDocsyのソースを参照してください。

対処

hugo.config[params.mermaid]の定義を削除します。 詳細はDocsyのDiscussionを参照してください。