Org-mode/Hugo/Cloudflare-Pagesでブログを作る

公式のQuick Start に従って、記事を書くサイトの枠組みを用意していきます。

1. Hugoのインストール
   主要なOSにおいてはパッケージが提供されています。

     sudo apt-get install hugo       # Debian
     sudo pacman -S hugo             # Arch Linux
     sudo dnf install hugo           # Fedora
     bew install hugo                # macOS

   Go製なので、バイナリをダウンロードしてパスに置くだけでも動いてくれます。

2. サイトの作成
   適当なディレクトリに移動して、下記コマンドを実行すると、 site_name というディレクトリ が作られ、その中にサイトの雛形一式が用意されます。

     hugo new site site_name              # site_nameという名前のサイトを作成する

3. Gitで初期化
   作成したサイトをCloudflare Pagesでホスティングする際、Gitのレポジトリが必要になるので、 初期化を済ませておきます。

     cd site_name
     git init

4. テーマの追加
   好みのテーマを探して、生成したサイトに追加します。公式のテーマ集だけでもバリエーション豊富です。

     git submodule add https://github.com/chosen/theme.git themes/chosen_theme

   追加したテーマを設定ファイルで指定しておきます。

     echo theme = \"chosen_theme\" >> config.toml

5. テーマの設定
   テーマごとに設定方法が異なります。 テーマのドキュメントを確認して、必要に応じて設定を行っておきます。

6. サイトの設定
   サイトのルートディレクトリ直下にある config.toml が サイト全体の設定ファイルです。 最低限 baseURL と title を設定しておきます。

     baseURL = 'https://site_name.pages.dev/' # Cloudflare Pages発行のURLを使う場合
     title = 'site_name'
     theme = "chosen_theme"

7. プレビュー
   生成したサイトは、ローカルでサーバーを動作させることで、 手元でプレビューすることができます。 サイトのルートディレクトリで下記のコマンドを実行すれば、プレビュー用サーバが動き出します。

     hugo server

   ブラウザで http://localhost:1313/ にアクセスすれば、 生成されたサイトの出来栄えが確認できます。

1. 記事ファイルの作成
   記事用の org ファイルは、 /content/posts 下に作成します。 1つのファイルから1つの記事が生成されます。

     .
     ├── archetypes
     │   └── default.md
     ├── config.toml
     ├── content        <- ここにpostsを作りorgファイルを置く
     ├── data
     ├── layouts
     ├── public
     ├── static
     └── themes

   content の下に作成するディレクトリの名前は任意に設定することができますが、 多くの場合 posts が無難です。詳細は補足をご覧ください。

2. 記事のメタ情報の設定
   Org-modeのexportオプション記法を使って、記事のメタ情報を設定できます。 Hugoが認識するオプションの一覧は公式ドキュメントで確認できます。 本記事で指定したオプションは以下の通りです。

     #+TITLE: Org-mode/Hugo/Cloudflare-Pagesでブログを作る
     #+AUTHOR: 0x60DF
     #+DATE: <2022-11-05 Sat 00:55>
     #+EMAIL: [email protected]
     #+LANGUAGE: ja
     #+slug: blog-in-org-mode-hugo-cloudflare-pages
     #+description: Org-modeで記事を作成し、Hugoで静的サイト生成、Cloudflare Pagesでホスティングする構成でのブログの作成記録。
     #+tags[]: Org-mode Hugo Emacs
     #+lastmod: <2022-11-05 Sat 22:45>
     #+isCJKLanguage: true

   tags のように、複数の値を設定するタイプのオプションは、 末尾に [] を書き添えて、空白区切りで指定してあげれば認識されます。 その他の注意点は、補足をご覧ください。

3. 本文の作成
   通常のOrg-modeの記法で記事を書いていきます。 もし、込み入ったことがしたいときは、可搬性が落ちますが、Hugoのスニペット機能 を使うことができます。

Cloudflare Pagesでは、Github/GitLabと接続することで、 レポジトリの取り込み、Hugoによるサイトの生成、公開を自動で行ってくれます。 CLIツール（ wrangler ）を使って、Gitレポジトリを直接デプロイすることもできますが、 Cloudflare PagesのスコープがWeb上のレポジトリとの接続に向かっていそうなので、 ここでは、Githubを使って、サイト公開を進めていきます。

1. Githubにレポジトリ設置
   ここまでで作成したデータ一式をGithubに設置します。

     git add .
     git commit -m "Commit massage."
     git remote add origin https://github.com/repository/path.git
     git push origin master

2. Cloudflare Pagesでプロジェクト作成
   Cloudflareでアカウントを作成して、Pagesの管理画面に入り、 プロジェクトを作成します。 案内に従って、接続するGithubのアカウントを指定します。 続いて、ホスティングするサイトのレポジトリを選びます。 最後に、サイト生成の設定を下図の通り行います。 デフォルトで使われるHugoのバージョンが古いので、使用しているテーマによっては、 ビルドが失敗します。 これを回避するために、環境変数を設定し、新しめのバージョンを指定しています。 また、コマンドにオプション（ --minify など）を渡したいときや、 サイトの設定で出力先ディレクトリを変えたときも、ここで設定できます。

以上で、作成したブログが公開されます。

content の下に置かれるディレクトリの名前は、 さらにその配下に置かれるファイルのタイプを規定します。 ここには任意の文字列を設定できますが、 Hugo内部でメタ情報として扱われるので、少し注意が必要です。 例えば、ページを生成するために、どのテンプレートを使うかを決める際、 タイプが参照されます。 テンプレートはテーマによって提供されるので、 選んだテーマによっては、使うべきタイプのガイドラインが示されているかもしれません。 特になければ、公式ドキュメントで例示されている posts の使用が前提になっている 可能性が高いと思われるので、 posts にしておくことで無用なトラブルを避けられます。

Hugoに直接 org ファイルを読み込ませる場合、当然のことながら、 パースにEmacsは使われません。 そのためか、オプションを指定する部分で、 書き方に気をつけないとうまく動作しないケースがあるようです。 本記事作成時に書き方を色々試したところ、オプション設定中に空行が挟まると、 以後のオプションが認識されないようでした。 オプションは、ファイルの先頭に、空行を開けず、素直な順序で記載しておくのがよさそうです。

Cloudflare Pagesでは、自動発行される site_name.pages.dev に加えて、 カスタムドメインを設定することもできます。 サイトの管理画面のメニューに、カスタムドメイン設定があるので、 画面の案内に従って必要事項を入力していけば、別途取得したドメインを設定することができます。 無事設定が完了すれば、SSLも有効化されます。

ドメインは、どこで取得してもよいのですが、DNSの管理はClaudflareに移す必要があります。 よそでDNSを管理している場合は、カスタムドメインを設定中に、 Cloudflareとドメインレジストラー両方で、DNS移行の設定をすることになります。 Cloudflareは、レジストラーサービス（Cloudflare Regstrar）も提供しており、 ここでドメインを登録しておくと、DNS移行の手間がかかりません。

カスタムドメインを設定する場合、Googleの検索エンジンに ドメインの登録を行っておいたほうが良さそうです。 Hugoでは、サイトマップも自動生成されるので、クロールを制限したいページなどがなければ、 サイトマップ作成の手間は必要ありません。 https://domain/sitemap.xml をGoogle Search Consoleに登録しておけば、 周回をかけてくれます。

本記事作成時、Google Analyticsが仕様のアップデートの過渡期（UA->GA4）にありました。 Hugoは、新旧どちらの仕様もサポートしてくれているので、 テーマが対応していれば、 config.toml で下記のように設定すればよいです。

  # For GA4
  googleAnalytics = 'G-XXXXXXXXXX'
  # For UA
  googleAnalytics = 'UA-XXXXXX-X'

残念ながら対応していない場合は、レイアウトを自作して、 Google Analytics用のコードをヘッダに埋め込む必要があります。 この場合、例えば、テーマの baseof.html を /layout/_default/ にコピーして、 ヘッダタグ部分に下記のような追記を行えば動作するはずです。

  <head>
    <!-- Original code of theme -->

    {{ template "_internal/google_analytics_async.html" . }}
    <!-- or -->
    {{ template "_internal/google_analytics.html" . }} <!-- recommended for GA4 -->
  </head>

実際に作成したGitレポジトリは、下記リンク先に設置してあります。
https://github.com/0x60df/kamitsumi