概要

技術ブログを書く際、検証環境と執筆環境が分かれていると、以下のような問題が発生します。

記事執筆と技術検証を行き来する手間が増える
記事の内容とコードの対応関係が分かりにくくなる

そこで、GitHub Codespacesを活用し、検証と執筆を同じ環境で行えるようにしました。
また、Next.jsのblog-starter-templateと連携し、記事の公開フローを整備します。

検証・執筆用レポジトリ

技術検証・ブログ執筆用のレポジトリは、以下のようなフォルダ構造としています。

.
├── 250301_記事1 (公開前)
│   ├── ...(検証用の作業ファイル)
│   ├── README.md
│   └──_resource
│           ├── cover.png
│           └── fig1.png
└── __PUBLISH__
    ├── 250101_記事2 (公開済み)
    │   ├── ...(検証用の作業ファイル)
    │   ├── README.md
    │   └── _resource
    │       ├── cover.png
    │       ├── fig1.png
    │       └── fig2.png
    ├── 250201_記事3 (公開済み)
    ...

検証〜執筆〜公開までは以下の順序で進めていきます。

検証
1テーマごとにフォルダを分け、技術検証を進める
検証環境の構築には、Github Codespaceのblankテンプレートを活用している。
blankテンプレートは、デフォルトでPythonやNode.js, Docker, Minikubeなどの、開発フェイズで頻繁に使用するソフトウェアがインストールされており、環境構築の手間を省くことができる。
執筆
検証が済んだら、同じフォルダ内のREADME.mdにまとめ記事を作成する(画像などの素材は_resourceに配置する)。
公開
執筆および推敲が完了したら、フォルダを丸ごと__PUBLISH__/以下に移動させることでブログでの公開対象にする。

ブログ用のレポジトリ

ブログアプリケーションとして、nextjsのblog-starterテンプレートを使用しました。

デフォルトだと_posts/というフォルダ以下のMarkdownファイルを読み込みますが、これをpublic/content_repo/__PUBLISH__に変更します。

src/lib/api.ts

import { Post } from "@/interfaces/post";
import fs from "fs";
import matter from "gray-matter";
import { join } from "path";

const contentDirName = "content_repo/__PUBLISH__";
const postsDirectory = join(process.cwd(), `public/${contentDirName}`)

...

ビルド時の設定

public/content_repoという名前で検証・執筆用のレポジトリをクローンするスクリプトを作成します。
ここではsparse-checkoutを使用し、README.mdと_resource以外の不要なファイルをクローンしないようにしています。
(Next.jsではpublic/以下のファイルは外部公開されてしまうため)

clone_content_repo.sh

#!/bin/bash

# -----
# コンテンツ管理レポジトリからmarkdownファイルとリソースデータのみをクローンする。
# -----

# token付きクローン
git clone --filter=blob:none --sparse ${REPOSITORY_NAME} public/content_repo
cd public/content_repo

# no-coneを有効化
git sparse-checkout init --no-cone

# __PUBLISH__/以下の、数字6文字(日付)から始まるディレクトリを取得
dirs=$(git ls-tree -d -r HEAD | awk '{print $4}' | grep -E '__PUBLISH__/[0-9]{6}')

# _resource, README.mdを指定
dirs_res=$(echo "$dirs" | sed 's|$|/_resource|')
dirs_md=$(echo "$dirs" | sed 's|$|/README.md|')

# 指定のファイル、フォルダのみをチェックアウト
git sparse-checkout set $dirs_res $dirs_md

cd ../..

nextjsのビルド時に、上記のスクリプトを実行するように設定します。
プラットフォームごとに方法は異なりますが、当ブログはAWS Amplifyを使用しているため、以下のようにamplify.yamlを設定しました。

amplify.yaml

version: 1
frontend:
  phases:
    preBuild:
      commands:
        - echo "pre-build phase"
        - echo "yarn install"
        - yarn install
        - echo "clone blog content repository"
        - . clone_content_repo.sh
    build:
      commands:
        - echo "build phase"
        - yarn run build
  artifacts:
    baseDirectory: .next
    files:
      - '**/*'
  cache:

まとめ

技術ブログ執筆と技術検証を同じ環境で行うことで、記事とコードの関連性を維持しながら効率よく作業できるようになりました。

GitHub Codespacesを活用し、技術検証とブログ執筆環境を統合
Next.jsのblog-starter-templateをカスタマイズし、ブログ記事の格納先を変更
AWS Amplifyのビルドフェーズで、Markdown記事のみをGitHubから取得するフローを作成

雰囲気エンジニアの備忘録

Atmosphere Engineer's Memorandum

概要

検証・執筆用レポジトリ

ブログ用のレポジトリ

ビルド時の設定

まとめ