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

Posted at 2026-02-25

こんにちは！株式会社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

設定手順：

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

設定後、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 ジョブだけが実行されます。

確認方法:

push 後、GitHub リポジトリ → Actions タブ
ワークフロー実行をクリック
build ジョブが ✅ になれば OK
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 テーマのカスタマイズとコメント機能の追加について書く予定です。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up