Netlify + Hugo + Decap CMS を使用したブログサイトを構築してみました

追記(2024-04-20)

筆者は現在Decap CMSを使用せず、ローカルのVisual Studio Codeで執筆しています。ブログサイトの公開先はNetlifyではなくCloudflare Pagesに変更しました。

よまししと申します。

静的サイトのホスティングサービスである Netlify と静的サイトジェネレーターである Hugo 、静的サイトジェネレーター用の CMS である Decap CMS を使用したブログサイトを構築し、その内容を備忘録としてまとめてみました。

本記事では前提の内容を満たした状態で、 Decap CMS 上で投稿を管理できる状態をゴールとしています。

前提

個人管理
Google アカウントで Decap CMS の管理画面にログインする
構築時のテーマは新規に作成したものを使用する
記事の時刻は日本時間で記録する
/posts/YYYY-MM-DD の記事を作成する
GitHub のリポジトリから Netlify にデプロイする

Hugo のインストール

Installation | Hugo を参考に Hugo のインストールを行います。

筆者は systemd を有効にした WSL 2 の Ubuntu を使用し、snap 経由でインストールを行いました。

ブログサイトを作成する

以下のコマンドを実行してブログサイトを作成しました。 <ブログサイト名> のディレクトリが作成されます。今後は作成されたディレクトリ内でコマンドを実行します。

hugo new site <ブログサイト名>

日本語のブログサイトを作成するため、hugo.toml を編集しました。

baseURL = 'https://example.org/'
-languageCode = 'en-us'
+languageCode = 'ja'
title = 'My New Hugo Site'
+hasCJKLanguage = true

編集の意図は以下です。

languageCode を ja に変更
- <html> タグの lang 属性に反映されます
  - 生成したテンプレートで参照される site.Language.LanguageCode に値が入る
hasCJKLanguage を有効にする
- Hugo に日本語を検知してもらうための設定で、 .Summary が長くなってしまう問題に対応

Configure Hugo | Hugo に設定可能な項目の一覧がありあす。

テーマファイルを新規に作成する

新規のテーマを作成してみたかったので、以下のコマンドを実行してテーマを作成しました。カスタマイズ、または既存テーマへの置き換えは後日行う予定です。

hugo new theme <テーマ名>

hugo.toml に以下を追記し、作成したテーマを使用するように設定しました。

theme = '<テーマ名>'

開発サーバーを起動する

hugo server コマンドを実行することで、手元の環境で開発サーバーが起動できます。

hugo server

hugo new theme で作成したテーマにはサンプルの投稿が含まれているため、それらの確認ができます。

テーマファイル内のサンプル投稿を削除する

themes/<テーマ名>/content/ ディレクトリを丸々削除しました。

Decap CMS を導入する

Web 上で投稿を管理するため、Decap CMS を導入しました。主に Decap CMS のドキュメントを参考にしています。

Decap CMS 上で生成されたコンテンツは、構築したサイトの Git リポジトリ上で管理されるみたいです。実際に触れてみるまでは、外部のデータベースに保存したコンテンツを使用してサイトを生成するものと勘違いしておりました。

管理画面用のファイルを追加する

Getting Started With Decap CMS を参考にして static/admin ディレクトリの中に index.html と config.yml を作成しました。

記事のファイル名を YYYY-MM-DD とし、記事の URL を /posts/YYYY-MM-DD とするような設定を主に行っています。

static/admin/index.html

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Content Manager</title>
    <script src="https://identity.netlify.com/v1/netlify-identity-widget.js"></script>
  </head>
  <body>
    <script src="https://unpkg.com/decap-cms@^3.0.0/dist/decap-cms.js"></script>
  </body>
</html>

static/admin/config.yml

collections は Configuration Options のドキュメントを参考に、 hugo new theme で生成された投稿サンプルに寄せた内容に設定しました。

追記(2024-01-08)

実際に運用し始めて修正した内容も追記しています。

locale: "ja"
local_backend: true
backend:
  name: git-gateway
  branch: main
media_folder: static/img
public_folder: /img
collections:
  - name: "post"
    label: "Post"
    folder: "content/posts"
    create: true
    slug: "{{fields.filename}}"
    preview_path: "posts/{{slug}}"
    fields:
      - { label: "Title", name: "title", widget: "string" }
      - {
          label: "File Name",
          name: "filename",
          widget: "datetime",
          date_format: "YYYY-MM-DD",
          time_format: false,
          format: "YYYY-MM-DD",
          hint: "作成されるファイル名と記事のURLで使用されます。新規作成時のみ有効な設定です。",
        }
      - {
          label: "Publish Date",
          name: "date",
          widget: "datetime",
          date_format: "YYYY-MM-DD",
          time_format: "HH:mm:ss+09:00",
          format: "YYYY-MM-DDTHH:mm:ss+09:00",
          hint: "公開日の設定です。未来の時刻では公開されません。",
        }
      - {
          label: "Draft",
          name: "draft",
          widget: "boolean",
          default: true,
          hint: "下書きとして保存するかどうかを設定します。",
        }
      - {
          label: "Tags",
          name: "tags",
          widget: "list",
          hint: "タグはカンマ区切りで指定します。",
        }
      - { label: "Body", name: "body", widget: "markdown" }

local_backend: ローカルの開発環境でも動作させるための設定です
- Beta Features! | Decap CMS | Open-Source Content Management System を参照

collections:

slug: 作成されるファイル名に関する設定です
- 最初に設定していた "{{year}}-{{month}}-{{day}}" の設定では UTC 時刻判定でファイル名が設定されてしまいます
  - 例えば日本時間の 1 時に作成すると、UTC 時刻準拠でその前日の日付に設定されます
- 後述する fields で定義した filename の YYYY-MM-DD を見るようにしています
preview_path: Decap CMS から記事のプレビューを行うためのパスの設定です
- 公開される記事の URL のパスになるように設定しました
fields の name が filename になっている設定 : ファイル名のための入力項目です
- Decap CMS の画面では使用しているデバイスの時刻が使用されるため、これらを利用する設定にしました
- 今回の要件では日付の情報は不要なので time_format は false にしています
- 作成時のみ有効な入力項目であるため、 hint でその旨を記載しています
- この項目の name を slug にしてしまうと、Hugo 側のリンク生成に影響が出てしまいます
  - 記事一覧で同じ日付の投稿が複数があると、全て最初に投稿したものへのリンクになってしまいます
fields の name が date になっている設定 : 公開日の入力項目です
- 保存されるファイルの date には日本時間で記録してほしかったため、 format を ISO 8601 の拡張方式でタイムゾーンを指定して設定しています
- 最初は HH:mm:ss の部分を hh:mm:ss としてしまい、午前中の時刻しか登録できずにハマりました
  - Moment.js | Docs
- どのタイムゾーンからでも日本時間で記録される設定にしているため、 time_format にも +09:00 を加えています

Netlify でサイトを作成する

Hugo versionを参考に netlify.toml をリポジトリルートに作成し、その状態で Netlify のサイトを作成しました。

[build]
command = "hugo"
publish = "public"

[build.environment]
HUGO_VERSION = "0.121.1"

[build.environment] の HUGO_VERSION にはローカルで使用している HUGO のバージョンを設定しました。設定しないとバージョンの兼ね合いでサイトの生成に失敗します。

管理画面にログインするための設定を行う

Netlify で作成したサイトの [Site configuration] から [Identity] を開き、以下の設定を行いました。

[Enable Identity] を選択して認証を有効にする
Registration preferences から [Configure] を選択し、[Invite only] に変更して [Save] を行う
- 個人管理にするため、認証を招待制に変更している
External providers から [Add provider] を選択し、[Google] を追加する
- 認証の設定は [Use default configuration] を選択した
Services から [Enable Git Gateway] を選択して Git Gateway を有効にする

これらの設定を行うことで、Google アカウントでログインするための準備と、Decap CMS から GitHub のリポジトリを操作する準備ができた状態になります。

管理画面にログインするためのユーザーを招待する

Netlify で作成したサイトのダッシュボードの左メニューにある [Integrations] から以下の設定を行い、ログインしたい Google アカウントから管理画面にログインできるように設定しました。

一覧から [Identity] を開き、Netlify Identity の [View] を選択する
[Invite users] から認証で使用したい Google アカウントのメールアドレスを入力し、[Send] を選択して招待メールを送信する
届いたメールの [Accept the invite] リンクを開き、作成したサイトに遷移したらOK

ユーザー招待については以下のブログを参考にしました。ありがとうございます。

Netlify Identityを使ってNetlify CMSのユーザー認証をする | 豆蔵デベロッパーサイト

管理画面へのログインを確認する

[Netlify で作成したサイトの URL]/admin/ にアクセスし、中央に表示される [Netlify Identity でログインする] から、 Google アカウントを使用したログインを試行しました。

ログインに成功して管理画面が表示されたら、Decap CMS 上で投稿を管理するための構築が済んだと言えるでしょう。

最後に

Hugo で生成する投稿を Web 経由で管理できる状態まで持っていくことができました。 Hugo については全然知らない状態なので、これから色々知っていければと思います。

自分の備忘録としてまとめてみましたが、本記事がどなたかのブログサイトの構築に役立てられれば幸いです。

最後まで読んでいただきありがとうございました。

よましし情報