Astro + GitHub + Cloudflare Pagesで技術ブログを立ち上げる

個人開発や技術学習をしていると、その過程でさまざまな疑問やトラブルに遭遇します。 その場では調べたり、ChatGPTと壁打ちしたりして解決できても、しばらくすると「どうやって解決したんだっけ？」となることがあります。 そこで、普段の開発・学習で得た知識をそのまま蓄積できる技術ナレッジベースを作ることにしました。

今回は、

  • Astro
  • Markdown / MDX
  • GitHub
  • Cloudflare Pages

というシンプルな構成で、Markdownファイルを書いてGitHubにpushすればWebサイトへ公開できる環境を構築します。

今回作りたかったもの

一番重視したのは、ブログそのものの運営に時間をかけないことです。 技術記事を書くためだけに新しいテーマを探すのではなく、普段の個人開発や技術学習で実際に疑問に思ったことを、そのまま記事として残せるようにしたいと考えました。 そのため、記事公開までの流れをできるだけ単純にします。

個人開発・技術学習
        ↓
疑問やトラブルが発生
        ↓
調査・ChatGPTとの壁打ち
        ↓
理解した内容をMarkdownで記事化
        ↓
GitHubへpush
        ↓
Cloudflare Pagesで公開

CMSなどは導入せず、記事そのものをMarkdownファイルとしてGitで管理します。

採用した技術構成

今回採用した構成は以下です。

役割 使用するもの
フレームワーク Astro
記事 Markdown / MDX
ソースコード管理 Git / GitHub
ホスティング Cloudflare Pages
開発環境 Windows + VS Code

Astroを使ってMarkdownから静的なHTMLを生成し、そのソースコードをGitHubで管理します。 GitHubとCloudflare Pagesを連携することで、GitHubへ変更をpushするとCloudflare側で自動的にビルド・デプロイされる構成にします。

事前に必要な環境

今回はWindows + VS Codeの環境で構築しました。

Astroプロジェクトを作成する前に、以下のコマンドが利用できる状態になっている必要があります。

node -v
npm --version
git --version

今回使用した環境では、以下のバージョンがインストール済みでした。

Node.js: v24.15.0
npm:     11.12.1
Git:     2.51.0.windows.1

npmはNode.jsのパッケージマネージャーで、通常はNode.jsをインストールすると一緒に利用できるようになります。 そのため、Node.jsがインストールされていない場合は、Astroプロジェクトを作成する前にNode.jsをインストールする必要があります。 また、今回はソースコードをGitHubで管理するため、Gitも事前にインストール済みの環境から開始しています。

Astroプロジェクトを作成する

まず初めに、エクスプローラーでプロジェクトを配置するための空のフォルダを作成します。そして、プロジェクトを配置するフォルダで、以下を実行しました。

npm create astro@latest

コマンドを実行するといくつか質問が始まります。 最初に以下の質問をされ、yで回答しました。

Need to install the following packages: 
create-astro@5.2.3 
Ok to proceed? (y)

次に、ディレクトリに関する質問をされました。

dir   Where should we create your new project?
         ./zany-zero

今回は既に作成済みのフォルダをプロジェクトルートとして使いたかったため、./zany-zeroを消し、作成先には . を指定しました。

次に、テンプレートの選択です。

tmpl How would you like to start your new project? 
    > A basic, helpful starter project (recommended) 
    — Use blog template 
    — Use docs (Starlight) template 
    — Use minimal (empty) template

技術ブログを立ち上げたかったため、

Use blog template

を選択しました。

この後、依存パッケージのインストールとGitリポジトリの初期化に関する質問が続きます。

deps Install dependencies? (recommended) 
● Yes ○ No
git Initialize a new git repository? (optional) 
● Yes ○ No

どちらも Yes を選択しました。これで質問は終わりです。

Blog templateを利用すると、最初からブログに必要な基本構造が生成されます。

src/
├─ components/
├─ content/
│  └─ blog/
├─ layouts/
├─ pages/
└─ styles/

特に重要なのが、

src/content/blog/

です。ここにMarkdownファイルを配置することで、ブログ記事として扱えます。

Markdown記事の構造

記事ファイルの先頭にはFrontmatterを記述します。 今回のサイトでは、記事のFrontmatterを次のような構成にしました。

  • title：記事タイトル
  • description：記事概要
  • pubDate：公開日
  • updatedDate：更新日（任意）
  • heroImage：記事固有の画像（任意）
  • tags：記事に関連する技術タグ

タグについてはAstroのBlog templateにはなかったため、src/content.config.ts のスキーマに追加しました。

tags: z.array(z.string()).default([]),

default([]) としているため、タグを指定しない記事でもエラーになりません。

サイトの最低限の構成を整える

AstroのBlog templateには、サンプル記事やAstro公式サイトへのリンクなどが含まれています。今回は最低限の技術ナレッジベースとして公開したかったため、不要なサンプル記事を削除し、サイトを次の構成に整理しました。

Home
├─ サイトの概要

Blog
├─ 記事一覧
└─ 個別記事

About
├─ このサイトについて
├─ 免責事項
└─ 連絡先

最初から検索、カテゴリ、コメント、アクセス解析などを追加することはせず、必要になった段階で追加することにしました。

本番用ビルドを確認する

ローカルで記事が表示できたら、本番用の静的ファイルを正常に生成できるか確認します。

npm run build

正常にビルドできると、

dist/

に公開用のファイルが生成されます。 今回の構成ではAstroの出力は static になっており、Cloudflare Pagesから静的サイトとして配信できます。

GitHubでソースコードを管理する

AstroプロジェクトはGitで管理し、GitHubへpushしました。 GitHubリポジトリについては、ブログそのものは公開する一方、ソースコードやMarkdown原稿のリポジトリを公開する必要はないと考えたため、Private Repositoryにしています。 つまり、

GitHub
Private Repository
        ↓
Cloudflare Pages
        ↓
公開Webサイト

という構成です。 GitHubリポジトリがPrivateでも、Cloudflare Pagesに必要なアクセス権限を付与すれば、公開サイトをデプロイできます。

GitHub上にPrivate Repositoryを作成した後、ローカルリポジトリにremoteを設定してpushしました。

git remote add origin <GitHubリポジトリのSSH URL>
git branch -M main
git push -u origin main

今回は、以前GitHubのSSH認証を設定済みだったため、SSHキーの作成・登録は行っていません。 SSH認証を設定していない環境では、別途GitHubとの認証設定が必要です。

Cloudflare PagesとGitHubを連携する

Cloudflare Pagesでは、GitHubの既存リポジトリをインポートしました。 GitHubとの連携時には、Cloudflareからアクセスできるリポジトリを、

Only select repositories

として、このサイトのリポジトリだけに限定しました。 ビルド設定は次のようにしています。

Production branch
main

Framework preset
Astro

Build command
npm run build

Build output directory
dist

設定後にデプロイすると、Cloudflare側でGitHubからソースコードが取得され、Astroのビルドが実行されます。 ビルドに成功すると、pages.dev のURLでサイトが公開されます。

今後の記事公開フロー

ここまで構築すると、普段の記事公開作業はかなり単純になります。 まず、

src/content/blog/

にMarkdown記事を追加します。 その後、Gitで変更をコミットします。

git add .
git commit -m "Add article about Astro setup"
git push

GitHubへのpushをCloudflare Pagesが検知すると、自動的にビルド・デプロイされます。 つまり、今後は基本的に、

Markdownを書く
↓
GitHubへpushする
↓
公開

だけです。

まとめ

今回は、Astro + Markdown / MDX + GitHub + Cloudflare Pagesを使って、個人用の技術ナレッジベースを構築しました。 最初から多機能なブログを作るのではなく、「普段の開発や学習で得た知識をすぐ残せること」を優先して、できるだけ単純な構成にしています。 実際に構築してみると、AstroのBlog templateだけでも記事サイトとして必要な基本機能はかなり揃っており、少しカスタマイズするだけでMarkdownベースの技術ブログとして利用できました。 今後はこの環境自体の開発に時間をかけすぎず、個人開発や技術学習で実際に遭遇した疑問やトラブルを中心に記事を蓄積していきます。