ご挨拶

本ブログの最初の投稿。
地方の大学を中退後、ものの見事に就活に苦戦し、フリーランスエンジニアとして独立し、なんとか生き延びてきた私。 前々から、何かしらアウトプットをしなければとは考えていたものの、重い腰が上がらず数年が経過。。。 ふと思い立ち、このブログを作ろうと考えたのが、2025/04/18(翌日が30歳の誕生日。20代最後の日)である。 本業でも行なっている、バックエンドエンジニア(フルスタックに片足をツッコミ気味), DevOps関連の投稿や、 趣味で行なっている、電子工作, 自宅サーバー, 3Dプリンタに関しての投稿も行いたい。

個人的な偏見だとも思うが、理系の技術職として、ふわっとした感じに受け取れる"です・ます調"の記載に気持ち悪さを感じる為、“である調"での記載をさせていただく。 ご容赦いただきたい。

本投稿のはじめに

このブログは、静的サイトジェネレーターの「Hugo」を使用して構築されている。この記事では、ブログの技術的な構成、使用しているツール、ワークフロー、こだわった点などについて解説する。Hugoに興味がある方や、半年後の自分の参考になれば幸いである。

テーマは、とりあえずで入れて、後々気に入らなければ変えれば良い程度で、適当に人気そうなものを採用した。初期構築には、最近本業の方でも積極的に利用が進められているcline+claude3.7の力を大いに借りた。(あまり細かいconfigが分かっていないので、ゆくゆくチューニングしていく予定。)

技術スタック

このブログは以下の技術スタックで構成されている：

  1. 静的サイトジェネレーター: Hugo
  2. テーマ: PaperMod
  3. ホスティング: Cloudflare Pages
  4. 開発環境: Node.js (v22.14.0)
  5. バージョン管理: Git

Hugoについて

Hugoは、Go言語で書かれた高速な静的サイトジェネレーターである。以下の特徴がある：

  • 高速なビルド: 数千ページのサイトでも数秒でビルド可能
  • クロスプラットフォーム: Windows、macOS、Linuxで動作
  • テーマ: 豊富なテーマが利用可能
  • Markdown: コンテンツはMarkdown形式で記述
  • ショートコード: 拡張機能を簡単に追加可能

はまりポイント

最初は、Hugoをhomebrew経由でインストールした(最新であった0.146.3)のだが、何故か本番ビルドの際にエラーで転けた。 しばらく彷徨った結果、直近のHugoのバージョンアップによる問題であることが判明。 (PaperModのレポジトリでIssueが上がっていた)

その為、どうせ他でも使うだろうとの目論見も含めて、npm経由でHugoを導入することにした。(私は自称、熱心なnode信者である。)
https://www.npmjs.com/package/hugo-extended
素敵なことに、npmのパッケージのバージョンとHugoのバージョンが一致している模様。
前述のIssue内にあった情報をもとに、一つ前のマイナーバージョンである、0.145.0を導入。

既に修正PRは作成されているので、マージされたらどこかのタイミングでアップデート予定

にしても、ブログを始めようとして、初っ端からハマるとは幸先の悪い。。。

プロジェクト構造

このブログのプロジェクト構造は以下のとおりである：

blog.untan.tech/
├── archetypes/        # 記事のテンプレート
├── assets/            # SCSS, JS, フォントなどのアセット
├── content/           # ブログコンテンツ
│   ├── posts/         # 記事ファイル
│   ├── archives.md    # アーカイブページ
│   └── search.md      # 検索ページ
├── data/              # Hugoデータファイル
├── layouts/           # カスタムレイアウト（必要に応じて）
├── static/            # 画像などの静的ファイル
├── themes/            # テーマ
│   └── PaperMod/      # PaperModテーマ
├── _scripts/          # カスタムスクリプト
├── hugo.toml          # サイト設定ファイル
└── package.json       # npm設定ファイル

設定ファイル（hugo.toml）

Hugoの設定はHugo.tomlファイルで管理している。主な設定項目は以下のとおりである：

baseURL = 'https://blog.untan.tech/'
languageCode = 'ja-jp'
title = 'エンジニアの裏庭'
theme = 'PaperMod'

# 基本設定
enableRobotsTXT = true
buildDrafts = false
buildFuture = false
buildExpired = false
enableEmoji = true

# PaperMod設定
[params]
  description = "技術系ブログ - バックエンドエンジニアリング、電子工作、3Dプリンタ、自宅サーバー、DevOps"
  defaultTheme = "auto" # dark, light, auto
  ShowReadingTime = true
  ShowShareButtons = true
  ShowPostNavLinks = true
  ShowBreadCrumbs = true
  ShowCodeCopyButtons = true
  ShowToc = true

記事の作成ワークフロー

新しい記事の作成

記事のタイトルをいちいち付けるのはとても面倒だと考え、最初はUUIDかULIDのようなものを検討していた。
しかし、Claude君に聞いたところ、SEO的には意味のある単語の方が好まれるらしい。(SEO周りは全然知見がない。。。)
なので、代替案として提案された、日付+意味のある文字列.mdを採用。 これを実現する為に、せっかく導入したので、nodeを活用した。

新しい記事を作成するには、以下のnpmスクリプトを使用する：

npm run new_page -name=記事の名前

このコマンドは、_scripts/new-page.jsスクリプトを実行し、以下のような処理を行う：

  1. 現在の日付を取得（YYYY-MM-DD形式）
  2. 指定された名前をハイフン区切りに正規化
  3. Hugo new posts/YYYY-MM-DD-記事の名前.mdコマンドを実行
  4. 記事のテンプレートファイルを生成

記事の編集

生成された記事ファイルは以下のようなフロントマター（メタデータ）を持つ：

---
title: "記事のタイトル"
date: 2025-04-18T21:43:33+09:00
draft: true
tags: ["タグ1", "タグ2"]
categories: ["カテゴリー"]
description: "記事の説明"
toc: true
---

これらのメタデータを編集し、本文をMarkdown形式で記述する。

ローカルプレビュー

記事を編集しながら、以下のコマンドでローカルプレビューを確認できる：

npm run start_dev

ブラウザで http://localhost:1313/ にアクセスすると、リアルタイムでプレビューが表示される。

PaperModテーマのカスタマイズ

このブログでは、PaperModテーマを使用している。PaperModは以下の特徴を持つ人気のHugoテーマである：

  • レスポンシブデザイン
  • ダークモード/ライトモードの切り替え
  • 検索機能
  • 目次（TOC）
  • コードのシンタックスハイライト
  • SEO対策

テーマのカスタマイズは主にhugo.tomlファイルで行うが、より高度なカスタマイズが必要な場合は、assets/css/extended/ディレクトリにCSSファイルを追加することも可能である。

デプロイ方法

このブログはCloudflare Pagesを使用してデプロイしている。デプロイの流れは以下のとおりである：

  1. GitHubリポジトリにコードをプッシュ
  2. Cloudflare PagesがGitHubリポジトリの変更を検知
  3. 自動的にHugoビルドを実行
  4. ビルドされたサイトをCloudflare CDN経由で配信

ビルド設定は以下のとおりである：

  • フレームワークプリセット: hugo
  • ビルドコマンド: hugo --minify
  • 公開ディレクトリ: public
  • 環境変数: HUGO_VERSION: 0.145.0

検索機能の実装

PaperModテーマには検索機能が組み込まれている。この機能を有効にするために、以下の設定を行っている：

  1. content/search.mdファイルの作成
  2. hugo.tomlの[outputs]セクションでJSON出力を有効化
  3. メニューに検索ページへのリンクを追加

まとめ

このブログは、Hugoという高速な静的サイトジェネレーターとPaperModというテーマを使用して構築されている。Markdownで記事を書き、GitHubでバージョン管理し、Cloudflare Pagesで自動デプロイする、というモダンなワークフローを採用している。

静的サイトジェネレーターを使用することで、以下のメリットがある：

  1. 高速なページ読み込み: 動的なサーバー処理が不要
  2. セキュリティ: 攻撃対象となるサーバーサイドコードがない
  3. 低コスト: 静的ファイルのホスティングは無料または低コスト
  4. バージョン管理: コンテンツをGitで管理可能

今後も、このブログを通じて技術的な知見を共有していく。