Docsyの適用
ゴール
下記は、Hugo + GitLab Pagesによるブログ環境の構成要素です。 ここでは、GitLabのHugoテーマ/コンテンツリポジトリに含まれるテーマ本体をDocsyに変更し、テーマ設定/コンテンツをDocsyサンプルに入れ替え、CI/CD設定をDocsy向けに変更して、サンプルサイトをビルド/公開することをゴールとします。
前提
「Hugo + GitLab Pagesブログサーバ」, 「VSCode開発クライアント」を実施し、GitLab Pages/Hugoテンプレートで構築されたサーバ環境とVisual Studio Codeによる開発クライアント環境がある前提で説明します。
適用方法
Visual Studio Codeでテーマ本体, テーマ設定/コンテンツを変更
-
Visual Studio Codeで管理するHugoリポジトリ資産の
/.gitlab-ci.yml
以外を削除します。 -
ブラウザでDocsyのサンプルプロジェクトを開き、すべてのファイルをダウンロードして、Visual Studio Codeで管理するHugoリポジトリ資産の
/
にコピーします。Hugoリポジトリ資産 ├ assets ← ダウンロードしたものをコピー ├ content ← ダウンロードしたものをコピー ├ layouts ← ダウンロードしたものをコピー ├ .gitlab-ci.yml ├ go.mod ← ダウンロードしたものをコピー ├ go.sum ← ダウンロードしたものをコピー └ hugo.toml ← ダウンロードしたものをコピー
なお、テーマ本体
/themes
はHugoリポジトリ資産として登録しません。 後続のCI/CD設定変更により、ビルド時に動的に取り込まれます。 -
Visual Studio Codeで
/hugo.toml
を開き、baseurl
をサンプルサイトのルートURLに変更します。
Visual Studio CodeでCI/CD設定をテーマに合わせて変更
-
Visual Studio Codeで管理するHugoリポジトリ資産の
/.gitlab-ci.yml
を削除します。 -
ブラウザでGitLab Pages/Hugoテンプレートの.gitlab-ci.ymlを開き、ダウンロードして、Visual Studio Codeで管理するHugoリポジトリ資産の
/
にコピーします。 -
Visual Studio Codeで
/.gitlab-ci.yml
を開き、image
にhugo_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.yml
のhigo 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を参照してください。