koki's blog

開発

GitHub PagesブログをVuePressからAstroへリニューアルした

2020年製のVuePressブログをAstroへ移行した理由と、設計・移行・運用改善の内容をまとめます。

Xでシェア
目次

AI利用の明示
今回のリニューアルでは、調査、技術選定の整理、設計、コード実装、検証をOpenAIのコーディングエージェント「Codex」が行いました。**この記事の構成と本文もCodexが作成しています。**サイト所有者は、移行方針やデザインなどの要件を選択し、内容を確認したうえで公開を指示しています。

このブログは2020年にVue.js系の静的サイトジェネレーターであるVuePress 1.5.4を使って作りました。それから時間が経ち、ライブラリだけでなく、デザインや公開方法も古い状態になっていました。

今回、GitHub Pagesはそのまま利用しながら、ブログ全体をAstroへ移行しました。この記事では、なぜAstroを選び、どのように構成と運用を変えたのかを記録します。

移行前の課題

リポジトリに残っていたのは、VuePressが生成したHTML、CSS、圧縮済みJavaScriptでした。生成元のMarkdownやビルド設定は現在のブランチから削除されており、次のような状態でした。

  • VuePress 1.5.4と古いテーマに依存している
  • 記事を生成済みHTMLから直接直す必要がある
  • package.jsonやテスト、ビルド手順がない
  • ハッシュ付きJavaScriptとHTMLの参照を手作業で合わせる必要がある
  • 公開前の下書きを安全に管理しにくい

表示はできていても、新しい記事を書いたりデザインを変更したりするには扱いにくい構成です。そこで「ライブラリを新しくする」だけではなく、記事を書くところから公開までを簡単にすることを移行の中心に置きました。

Astroを選んだ理由

移行先としてAstro、VitePress、Eleventyを比較し、Astroを選びました。

ブログを静的HTMLとして配信できる

GitHub Pagesは静的ファイルの配信に向いています。Astroは各ページをビルド時にHTMLへ変換できるため、閲覧時に大きなJavaScriptアプリを起動する必要がありません。

今回クライアント側で動くJavaScriptは、ライト／ダークテーマの切り替えだけです。記事本文や一覧はHTMLとして生成されるため、構成が単純で表示も軽くなります。

Markdownを型付きで管理できる

AstroのContent Collectionsを利用し、記事のfrontmatterを検証しています。

title: 記事タイトル
description: 記事の概要
publishedAt: 2026-09-03
category: 開発
tags:
  - Astro
draft: true

必須項目の不足や日付形式の誤りはnpm run checkで検出できます。記事ファイルを追加するだけで、記事ページ、一覧、カテゴリー、タグ、RSS、サイトマップへ反映されます。

GitHub Pagesへの公式デプロイ手段がある

Astro公式のGitHub Actionを使い、mainへの変更を自動でビルド、デプロイする構成にしました。生成済みファイルを人がコミットする必要はありません。

VitePressはVueを継続できる点が魅力でしたが、標準構成はドキュメントサイト寄りです。Eleventyは依存が少なく堅実ですが、今回はコンテンツの型検証、ページ設計、公式連携のバランスからAstroが合っていると判断しました。

移行で変更したこと

生成済みHTMLから4記事を復元

既存ページから本文、見出し、コード、表、カテゴリー、タグを取り出し、4記事をMarkdownへ戻しました。画像もpublic/img/posts/へ整理し、空白を含まない分かりやすいファイル名へ変更しています。

記事URLは、日付と英字slugを使う次の形式へ刷新しました。

/posts/YYYY/MM/DD/article-slug/

今回は構成を単純化する方針を選び、旧URLからの転送ページは設けていません。

デザインを作り直した

既存テーマは使用せず、AstroコンポーネントとCSSで新しいデザインを作りました。

  • 日本語本文を読みやすくする余白、行間、本文幅
  • モバイルとデスクトップに対応したレスポンシブ表示
  • OS設定と手動選択に対応するライト／ダークテーマ
  • キーボードフォーカスやコントラストを考慮した操作性
  • 記事の目次、前後記事、カテゴリー、タグへの導線

UIライブラリやCSSフレームワークは追加していません。依存を増やさず、必要な見た目だけを実装するためです。

SEOとフィードを自動生成

各ページのdescription、canonical URL、Open Graph、Twitter Cardを共通レイアウトから出力します。RSSとサイトマップも記事データから自動生成するようにしました。

手書きのrobots.txtにあった綴り間違いや、ページ追加時にサイトマップを更新し忘れる問題も解消しています。

下書きと公開の運用

新しい記事はdraft: trueで書き始めます。ローカル開発環境では下書きを確認できますが、本番ビルドでは記事ページだけでなく、一覧、カテゴリー、タグ、RSS、サイトマップからも除外されます。

公開までの流れは次のようになりました。

  1. Markdownで記事を書く
  2. npm run devで下書きを確認する
  3. draft: falseへ変更する
  4. 型検査、ビルド、生成後テストを実行する
  5. Pull Requestをmainへマージする
  6. GitHub ActionsがGitHub Pagesへ自動公開する
npm run check
npm run build
npm test

npm testでは、生成されたページの内部リンク、画像、SEOメタデータ、RSS、サイトマップを検査します。依存パッケージとGitHub ActionsはDependabotが毎月確認します。

AIと一緒にリニューアルして感じたこと

今回のように生成元が失われ、生成済みHTMLだけが残っているサイトでも、AIは構造の調査、記事の抽出、移行コードの作成、ビルドエラーの修正を連続して進められました。特に、実ブラウザで狭い画面のはみ出しを発見し、CSSを修正して再確認するところまで一つの流れで行えたのは便利でした。

一方で、技術選定の優先順位、既存URLを維持するか、プロフィールをどこまで残すかといった判断は、サイト所有者が決める必要があります。AIに実装を任せる場合でも、採用した方針、検証結果、AIの関与を記録しておくことが大切だと感じます。

このブログでは、今後もMarkdownを追加するだけで記事を書けます。まずは、更新を再開しやすい土台を作るという今回の目的を達成できました。

本記事は上記のとおり、OpenAI Codexがリニューアル作業の記録をもとに執筆しました。