DearOneテックブログPublicationへの投稿
📖

Claude Code + Jekyll + VSCode でテックブログ環境を構築した話

shin
に公開
Jekyll
VS Code
GitHub Pages
Claude Code
tech

こんにちは！株式会社DearOneの申（シン）です。バックエンドとインフラを中心に、幅広く担当しています。

会社から「テックブログを書いてほしい」と依頼を受け、初めてのことで悩みつつも、構築や運用の手間を最小限に抑える構成を模索しました。

結論として選んだのは、 Jekyll + GitHub Pages + VSCode の組み合わせ。さらに今回は、開発効率化のために話題の Claude Code も活用しています。 今回はその選定理由や構築の流れについてお話します。

Jekyll vs Hugo 、どっちを選ぶ？

静的サイトジェネレーター（SSG）の選定にあたっては、 Jekyll と Hugo の2つを検討しました。

Jekyll は Ruby ベース、Hugo は Go ベースで作られています。ビルド速度に関しては Hugo が圧倒的に速いですが、うちのチームの状況で決め手となったのは GitHub Pages のネイティブサポートの有無でした。

現時点では自社サーバーへのデプロイ予定はなく、別途 CI/CD パイプラインを構築するのはオーバーエンジニアリングだと判断しました。Jekyll は GitHub に push するだけで自動的にビルド・デプロイが行われます。Hugo の場合は GitHub Actions を別途設定する必要があります。

結論：手っ取り早く始めたいなら Jekyllがおすすめ。

VSCode の設定

Markdown + Jekyll の作業に役立つ拡張機能を紹介します。

必須

  • Markdown All in One - ショートカット、目次自動生成、プレビュー
  • markdownlint - Markdown 文法チェック

Jekyll 特化

  • Jekyll Syntax Support - Liquid テンプレート構文のハイライト
  • Jekyll Snippets - front matter などよく使うコードスニペット

任意

  • Front Matter - タグ・カテゴリ管理、SEO チェック

インストール後、Ctrl/Cmd + K V で Markdown プレビューを開いておくと、書きながらすぐ確認できます。

ディレクトリ構成

Jekyll の標準構成に従いました。

techblog/
├── _posts/          # 公開記事
├── _drafts/         # 下書き（ビルド対象外）
├── assets/
│   └── images/      # 画像
├── _config.yml      # Jekyll 設定
├── .gitignore
└── README.md

_config.yml の基本設定：

# Site settings
title: DearOne Tech Blog
description: 技術ブログ
baseurl: ""
url: ""

# Build settings
markdown: kramdown
theme: minima

macOS 環境構築 (Sequoia 15.x)

Jekyll をローカル環境で動かすには Ruby 環境が必要です。macOS にプリインストールされているシステム Ruby は権限周りで問題が発生しやすいため、別途 Ruby をインストールすることを強くおすすめします。

1. Homebrew インストール（既にあればスキップ）

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. Ruby バージョンマネージャをインストール (chruby + ruby-install)

brew install chruby ruby-install

3. Ruby インストール

ruby-install ruby 3.4.1

4. シェル設定（zsh の場合。bash なら .zshrc → .bash_profile）

echo "source $(brew --prefix)/opt/chruby/share/chruby/chruby.sh" >> ~/.zshrc
echo "source $(brew --prefix)/opt/chruby/share/chruby/auto.sh" >> ~/.zshrc
echo "chruby ruby-3.4.1" >> ~/.zshrc

source ~/.zshrc

5. ターミナル再起動後に確認

ruby -v
# ruby 3.4.1 (2024-12-25 revision ...) と表示されれば OK
ruby 3.4.1 (2024-12-25 revision 48d4efcb85) +PRISM [arm64-darwin24]

6. Jekyll インストール

gem install jekyll bundler

7. プロジェクト初期化

cd techblog
bundle init

Gemfile に以下を追加：

# frozen_string_literal: true

source "https://rubygems.org"

gem "jekyll", "~> 4.4"
gem "webrick"  # Required for Ruby 3.x
gem "minima"   # Default theme

# GitHub Pages
group :jekyll_plugins do
  gem "jekyll-feed"
  gem "jekyll-seo-tag"
end

bundle install

8. ローカルサーバー起動

bundle exec jekyll serve

Tip: プロジェクトルートに .ruby-version ファイルを作成し 3.4.1 と書いておくと、そのフォルダに入ったとき chruby が自動で Ruby バージョンを切り替えてくれる。

echo "ruby-3.4.1" > .ruby-version

ローカル実行するとディレクトリ一覧が表示される。index.md を追加して解決する。

---
layout: home
---

CLAUDE.md などプロジェクトルートにあるファイルが _site に含まれてしまうため、
_config.yml にexcludeを追加

# ...
# Exclude from processing
exclude:
  - README.md
  - CLAUDE.md
  - Gemfile
  - Gemfile.lock

9. 動作確認

設定が完了したら再度ローカルサーバーを起動する。

bundle exec jekyll serve

テーマの Sass で Deprecation Warning が出るが、動作には問題ない。

Warning: 6 repetitive deprecation warnings omitted.

http://localhost:4000 にアクセスして表示を確認する。

GitHub Pages へのデプロイ方法

1. リポジトリの Settings を開く

Settings → Pages → Source でブランチを main に設定する。

2. 記事を書いて push

git add .
git commit -m "Add: 最初の投稿"
git push origin main

3. デプロイを確認

1〜2分後に https://{username}.github.io/{repo-name} で確認できる。

2024年6月以降、GitHub Pages は GitHub Actions ベースで動作するようになりました。従来通りブランチデプロイも可能ですが、内部的には Actions が動いています。

GitHub Actions でのビルド設定

Jekyll のビルドとデプロイを自動化するために、 GitHub Actions の設定ファイルを作成します。.github/workflows/jekyll.yml として保存するすることで、GitHub側に自動で認識されるようになります。

name: Deploy Jekyll site to Pages

on:
  push:
    branches: ["main"]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.2'
          bundler-cache: true

      - name: Setup Pages
        uses: actions/configure-pages@v4

      - name: Build with Jekyll
        run: bundle exec jekyll build
        env:
          JEKYLL_ENV: production

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

これで main ブランチに push するたびに自動でビルド・デプロイされます。

GitHub Pages の設定

初回は GitHub Pages の設定を有効化する必要があります。設定しないと actions/configure-pages@v4 でエラーになってしまうので注意してください。

Error: Get Pages site failed. Please verify that the repository has Pages enabled
and configured to build using GitHub Actions

設定手順：

  1. リポジトリの Settings を開く
  2. 左メニューから Pages を選択
  3. Source を GitHub Actions に変更

github-pages.png

設定後、Actions を再実行すればデプロイが成功します。

デプロイせずに動作確認したい場合

まずは GitHub Actions が正しく動くか確認したい、という場合は deploy ジョブをコメントアウトすれば OKです。

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3

#  deploy:
#    environment:
#      name: github-pages
#      url: ${{ steps.deployment.outputs.page_url }}
#    runs-on: ubuntu-latest
#    needs: build
#    steps:
#      - name: Deploy to GitHub Pages
#        id: deployment
#        uses: actions/deploy-pages@v4

この状態で push すると、build ジョブだけが実行されます。

確認方法:

  1. push 後、GitHub リポジトリ → Actions タブ
  2. ワークフロー実行をクリック
  3. build ジョブが ✅ になれば OK
  4. Artifacts セクションに github-pages が生成されていれば成功

プライベート公開について

結論から言うと、GitHub Pages のプライベート公開は GitHub Enterprise Cloud でのみ可能です。個人アカウントや通常の Organization プランでは、private repository であっても Pages 自体はインターネット上に公開されてしまいます。

自分だけ見たい場合の代替案：

1. ローカルプレビューのみ（おすすめ）

bundle exec jekyll serve
# http://localhost:4000 で確認

デプロイせずローカルで確認するだけなら最もシンプル。

2. Netlify / Vercel + 認証

Netlify や Vercel なら無料プランでもパスワード保護やチームメンバー限定公開ができます。

3. Basic認証付きの自社サーバー

将来的に自社サーバーを使う予定があるなら、nginx や Apache で Basic 認証をかける方法もあります。

今回は公開前の確認用途なので、ローカルプレビューで進めることにしました。

Claude Code の設定

Claude Code をプロジェクトで初めて使うときは /init コマンドで CLAUDE.md ファイルを生成します。このファイルにプロジェクトのコンテキストを書いておくことで、Claude が状況を理解してより正確にサポートしてくれます。

claude /init

Jekyll テックブログ用に作成した CLAUDE.md：

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

DearOne社の技術ブログ。Jekyll 4.x + GitHub Actionsで運用。

### Claudeの役割

- 記事の作成・校正サポート（日本語）
- ローカルプレビュー確認（`bundle exec jekyll serve --drafts`）

### Why Jekyll?

Hugo（Go製）より遅いが、Ruby製でシンプル。

## Commands

```bash
# ローカルサーバー起動
bundle exec jekyll serve

# 下書きを含むプレビュー
bundle exec jekyll serve --drafts

# 下書き + ライブリロード（編集時に自動更新）
bundle exec jekyll serve --drafts --livereload

# ビルド
bundle exec jekyll build
```

ローカルサーバー: http://localhost:4000

## 記事作成ルール

- **ファイル位置**: `_posts/`（公開）、`_drafts/`（下書き）
- **ファイル名**: `YYYY-MM-DD-slug.md`（例: `2025-01-08-my-first-post.md`）
- **画像パス**: `/assets/images/`

### Front Matter（必須）

```yaml
---
layout: post
title: "記事タイトル"
date: 2025-01-08 10:00:00 +0900
categories: [category1, category2]
tags: [tag1, tag2]
---
```

## トーンマナー

- 技術ブログだが堅苦しくならないように
- ですます調または、だ・である調

Tip: backtick quote(`) 4つ以上にすることでコードブロックをネストさせることができます
※参考 Markdownでコードブロックをネストさせる

これで「新しい記事書いて」と入力するだけで、ファイル名規則、front matter、トーンマナーを自動で合わせてくれます。

Claude Code の活用例

> このテーマでテックブログの下書きを作って
> もう少しカジュアルなトーンに変えて
> main ブランチにコミットして push して

下書き作成 → Claude Code、細部の調整 → VSCode、という使い分けが効率的でした。

下書きを公開する

記事が完成したら _drafts/ から _posts/ に移動します。

# ファイル名に日付を付けて移動
mv _drafts/tech-blog-setup.md _posts/2025-01-08-tech-blog-setup.md

ローカルで最終確認：

bundle exec jekyll serve

問題なければ push してデプロイを行います。

次回は Jekyll テーマのカスタマイズとコメント機能の追加について書く予定です。

本記事のオリジナル（Qiita版）はこちら。

DearOneテックブログ
DearOneテックブログPublication

株式会社DearOneのエンジニアによる公式テックブログです。 「ModuleApps2.0」や「ARUTANA」など自社プロダクトの開発の裏側や工夫、日々のTipsをお届けします。

Discussion