このサイトは Astro というフレームワークで作っています。Claude Code に「Astro で作って」と頼めばサイトはできあがりますが、Astro に何ができるのかを知らないと、次に何を頼めばよいのかがわかりません。
そこで、サイトやブログを作るときに使う Astro の標準機能を、このサイトで実際にどう使っているかとあわせて紹介します。このサイトでまだ使っていない機能は、公式ドキュメントをもとにした解説にとどめています。
Astro をほかのツールと比べた結果や、HTML だけのサイトから移行する手順は、次の記事に書いています。
比較と移行の手順サンプルサイトを Astro に移行して Cloudflare で公開するまでHTML だけで作ったサンプルサイトを静的サイトジェネレーター Astro へ移行し、Cloudflare Workers で再公開するまでの最短手順と、Next.js・Hugo・11ty との比較を解説します。
機能の名前と書き方は、2026年9月15日に Astro の公式ドキュメント（Astro 7）で確認した内容です。このサイトは Astro 7.3.2 で動いています。
Astro は HTML を書き出すためのフレームワーク
Astro は、Web サイトを作るためのフレームワークです。ヘッダーや記事本文などの材料を組み合わせて、ビルド（公開用のファイルを作る作業）のときに HTML と CSS を書き出します。できあがったファイルを配信するだけなので、Cloudflare Workers のような配信サービスとの相性が良いツールです。
特徴を3つに絞ると、次のようになります。
- HTML に近い書き方：
.astroファイルの見た目はほぼ HTML なので、HTML と CSS がわかれば読み始められる - JavaScript は標準でゼロ：ボタンの動きなど、必要な部品にだけ JavaScript を付けられる
- サーバー側の処理にも広げられる：フォームの送信のような処理が必要になったら、ページ単位でサーバーで動かせる
2026年6月22日に公開された Astro 7 では、.astro ファイルを変換する部分と Markdown を処理する部分が Rust という言語で書き直され、ビルドが速くなりました。公式ブログでは、ベンチマークで15〜61%速くなったと紹介されています。
補足：古い解説記事の手順は Astro 7 でそのまま動かないことがある
Astro 7 から、Markdown の処理は Sätteri という新しい仕組みが標準になりました。それまでの remark・rehype 用のプラグインを使う場合は、@astrojs/markdown-remark を自分で入れ直す必要があります。
ネットで見つけた手順を Claude Code に試してもらうときは、「この手順は Astro のどのバージョン向けか確かめてから進めて」と一言添えておくと、バージョンの違いによる失敗を減らせます。
コンポーネントとレイアウト：共通パーツを1か所で管理する
コンポーネントは、ヘッダーやフッターのようなページの部品を1つのファイルに切り出したものです。一度作れば、どのページからでも読み込んで使えます。ナビゲーションのリンクを1つ足すときも、ヘッダーのファイルを直すだけで全ページに反映されます。
.astro ファイルは、上下2つの部分に分かれています。このサイトの記事で使っている囲み枠（この記事の「補足」の枠）を、流れだけ抜き出すと次のようになります。
---
// ① 上の部分：ビルドのときに動くスクリプト
interface Props {
title: string;
type?: 'hint' | 'caution' | 'info' | 'check';
}
const { title, type = 'hint' } = Astro.props;
---
<!-- ② 下の部分：書き出す HTML -->
<div class={'note note-' + type}>
<p class="note-title">{title}</p>
<slot />
</div>① の --- で囲んだ部分は、ビルドのときにだけ動きます。ここに書いたコードは閲覧者のブラウザには送られません。Astro.props は、部品を使う側から渡された値（ここではタイトルと枠の種類）です。
② の <slot /> は、部品を使う側がタグの間に書いた中身を差し込む場所です。記事では次のように書くと、<slot /> の位置に段落が入ります。
<Note type="info" title="補足：…">
<p>ここに書いた段落が、slot の位置に入ります。</p>
</Note>ページ全体の枠（<html> や <head>、ヘッダー、フッター）も、同じ仕組みでレイアウトとして1つにまとめられます。このサイトでは BaseLayout.astro に共通の <head> やヘッダーを置き、各ページはその中身だけを書いています。
.astro ファイルに <style> を書くと、その CSS はそのコンポーネントの中にだけ適用されます。部品ごとに CSS を書いても、ほかの部品の見た目を崩す心配がありません。なお、このサイトはデザインを1つの CSS ファイルで管理しているので、この仕組みは使っていません。
全ページに同じ HTML で書いているお知らせのバナーを、Astro のコンポーネントにしてください。
- ファイルは src/components/NoticeBanner.astro にする
- お知らせの文章とリンク先は、使う側から props で渡せるようにする
- 置き換える前と後で、表示が変わっていないかブラウザで確認するファイルベースルーティング：置いた場所がそのまま URL になる
ルーティングは、「どの URL を開いたら、どのページを表示するか」の決まりのことです。Astro では、src/pages フォルダにファイルを置くと、その場所と名前がそのまま URL になります。設定ファイルに URL を書き足す必要はありません。
このサイトの src/pages にあるファイルと、公開される URL は次のとおりです。
| src/pages に置くファイル | 公開される URL | 中身 |
|---|---|---|
index.astro | / | トップページ |
about.astro | /about | 運営者情報 |
articles/[slug].astro | /articles/記事名 | 記事ページ（記事の数だけできる） |
404.astro | 存在しない URL を開いたとき | 「ページが見つかりません」のページ |
rss.xml.ts | /rss.xml | RSS（HTML ではないファイル） |
表の3行目の [slug] は、「ここに記事の名前が入る」という穴あきの名前です。ファイルの中に getStaticPaths() という関数を書いて記事の一覧を返すと、Astro がビルドのときに記事1本ずつのページを作ります。記事が5本なら、このファイル1つから5ページができます。
5行目のように、.ts や .js のファイルからは HTML 以外のファイルも作れます。このようなファイルをエンドポイントと呼びます。このサイトでは、RSS のほかにアイキャッチ画像もエンドポイントで作っています。
エンドポイントで画像を作る例記事のアイキャッチ画像を自動で作る：Astro のビルドで OGP 画像ができる仕組み記事を書くたびに画像編集ソフトでアイキャッチを作るのをやめて、Astro のビルドのときに記事のタイトルから OGP 画像を自動で作る方法を解説します。画像生成 AI を使わずにビルドするだけで画像ができる理由と、料金がかからない理由もあわせて紹介します。
ファイル名の先頭に _（アンダースコア）を付けると、そのファイルはページになりません。作りかけのページや、ページの近くに置いておきたい部品に使えます。
Markdown・MDX とコンテンツコレクション：記事を増やせる形にする
ブログとして使うときの中心になるのが、この節の機能です。記事を Markdown で書き、記事の一覧やカテゴリーのページは自動で作る、という形にできます。
Markdown と MDX で記事を書く
Astro は、Markdown で書いたファイルを標準で HTML にします。表や打ち消し線などを書ける GitHub Flavored Markdown、コードの色分け（Shiki）、見出しへの ID の自動付与も、設定なしで使えます。
MDX は、Markdown の中にコンポーネントを置ける書き方です。公式のインテグレーション @astrojs/mdx を入れると使えるようになります。この記事も MDX で書いていて、上の「補足」の枠や、記事へのリンクカードはコンポーネントです。
運用のコツ：見出しの ID を短い英字にする
見出しの ID は自動で付きますが、日本語の見出しからは長い日本語の ID になります。このサイトでは Markdown の処理の設定を変えて、見出しの後ろに {#routing} のように書いた短い英字を ID にしています。目次のリンク先の URL が読みやすくなります。
コンテンツコレクションで記事の項目をそろえる
コンテンツコレクションは、記事のような同じ種類のデータをまとめて扱う仕組みです。src/content.config.ts に、どのフォルダの記事を読み込むかと、記事の先頭に書く項目（frontmatter）の決まりを書いておきます。
const articles = defineCollection({
// src/content/articles にある .md と .mdx を読み込む
loader: glob({ pattern: '**/*.{md,mdx}', base: './src/content/articles' }),
// 記事の先頭に書く項目の決まり
schema: z.object({
title: z.string(), // タイトルは文字列で必須
description: z.string(),
pubDate: z.coerce.date(), // 公開日は日付として読む
updatedDate: z.coerce.date().optional(), // 更新日は書かなくてもよい
tags: z.array(z.string()).default([]),
}),
});この決まりに合わない記事があると、Astro はビルドのときにエラーで知らせてくれます。たとえば title を書き忘れた記事は、公開される前にビルドが止まります。記事の数が増えても、一覧に空のタイトルが並ぶような失敗を防げます。
読み込んだ記事は、getCollection('articles') のように呼ぶと一覧で受け取れます。このサイトのトップページの新着記事、カテゴリーのページ、記事の下の「関連記事」は、どれもこの一覧から作っています。記事ファイルを1つ追加すると、これらのページにも自動で並びます。
記事の frontmatter に「難易度」の項目を追加してください。
- 値は「入門」「中級」のどちらかにする
- 書かなかった記事は「入門」として扱う
- 記事ページの公開日の横と、記事一覧のカードに表示する
- 既存の記事にも、内容に合わせて値を入れる
- ビルドが通ることと、表示をブラウザで確認するJavaScript は必要な部分だけ：script とアイランド
Astro は、標準では JavaScript を1行も出力しません。コンポーネントの --- の中に書いたコードはビルドのときに動くだけで、ブラウザには HTML だけが届きます。ブラウザで動く処理が必要なときは、次の2つの方法で足します。
script タグで小さな動きを付ける
コンポーネントに <script> を書くと、ブラウザで動く JavaScript になります。Astro はこの <script> をそのまま出力するのではなく、TypeScript で書けるようにしたり、同じ部品を何回使っても1回だけ読み込むようにしたりと、手を加えてから出力します。
このサイトのコードブロック右上の「コピー」ボタンや、目次、テーマの切り替えは、この方法で作っています。コードブロックは1つの記事に何個も置きますが、コピーボタンのスクリプトは1回しか読み込まれません。
<script is:inline> と書くと、Astro は手を加えずに書いたとおりに出力します。このサイトでは、保存したテーマ（ダークかライトか）を画面が表示される前に反映するスクリプトに使っています。まとめて読み込まれるのを待つと、一瞬だけ違う色で表示されてしまうからです。
アイランドで React などの部品を使う
React や Vue、Svelte などで作った部品も、公式のインテグレーションを入れれば .astro のページの中で使えます。このとき、ページの大部分は HTML のままにしておき、動きが必要な部品にだけ JavaScript を読み込ませます。JavaScript で動く部品が HTML のページの中に島のように点在するので、この部品をアイランド（島）と呼びます。
JavaScript を読み込むタイミングは、部品に付ける client: で始まる指定で選びます。
| 指定 | JavaScript を読み込むタイミング | 向いている部品の例 |
|---|---|---|
client:load | ページを開いたらすぐ | すぐに操作する検索ボックス |
client:idle | ページの読み込みが落ち着いてから | 急がないチャットの窓 |
client:visible | 部品が画面に入ってから | ページの下のほうにあるコメント欄 |
client:media | 指定した画面幅などの条件を満たしたとき | スマートフォンだけで使うメニュー |
client:only | ビルドでは HTML を作らず、ブラウザでだけ表示する | ブラウザの情報がないと表示できない部品 |
client: の指定は、React などで作った部品にだけ使えます。.astro のコンポーネントには使えません。このサイトは <script> だけで足りているので、アイランドは使っていません。
画像の最適化：Image と Picture
astro:assets から読み込める <Image /> コンポーネントを使うと、画像をそのまま載せるより軽く表示できます。<Image /> がビルドのときにしてくれることは、次のとおりです。
- 画像の幅と高さを
widthとheightに書き込む（読み込み中にレイアウトがずれるのを防ぐ） - 軽い WebP 形式に変換する
loading="lazy"とdecoding="async"を付けて、画面に入るまで読み込みを後回しにする
<Picture /> を使うと、AVIF と WebP のように複数の形式を用意して、ブラウザが対応している形式を選んで表示させられます。
最適化されるのは、src フォルダに置いた画像です。public フォルダに置いた画像は、手を加えずにそのまま配信されます。また、ほかのサイトにある画像を最適化するには、設定の image.domains などで、そのサイトを許可しておく必要があります。
このサイトは記事に写真を載せていないので、この機能はまだ使っていません。スクリーンショットや写真を載せるようになったら、最初に取り入れたい機能です。
記事に載せるスクリーンショットを、Astro の Image コンポーネントで表示するようにしてください。
- 画像は src/assets/articles/記事名/ に置く
- 記事の MDX から、画像のファイル名と説明文（alt）を渡すだけで使えるようにする
- 変換前と変換後の画像のファイルサイズを比べて教えてください公式のインテグレーションとパッケージ：サイトマップ・RSS・MDX
インテグレーションは、Astro に機能を足すための追加部品です。次のコマンドで入れると、パッケージのインストールと astro.config.mjs への設定の書き込みを、まとめて済ませられます。
npx astro add mdx sitemapブログでよく使うのは、次の3つです。
| 名前 | できること | 種類 |
|---|---|---|
@astrojs/mdx | 記事の中でコンポーネントを使える MDX を書けるようにする | インテグレーション |
@astrojs/sitemap | 検索エンジン向けに、サイトのページ一覧（サイトマップ）をビルドのときに作る | インテグレーション |
@astrojs/rss | 更新情報を配信する RSS を作る | エンドポイントの中で呼び出すパッケージ |
サイトマップと RSS には、サイトの URL が必要です。astro.config.mjs の site に公開先の URL を書いておきます。
このサイトでは、3つとも使っています。サイトマップには、記事がまだ1本もないカテゴリーのページを載せないよう、条件を1つ足しています。
export default defineConfig({
site: 'https://growai-lab.com',
integrations: [
mdx(),
// 記事のないカテゴリーのページは、サイトマップに載せない
sitemap({ filter: (page) => !isEmptyCategoryPage(page) }),
],
});RSS は、src/pages/rss.xml.ts というエンドポイントの中で @astrojs/rss を呼び出し、コンテンツコレクションから受け取った記事の一覧を渡して作っています。
ページの移動を速くする：プリフェッチとページ遷移
ここからの機能は、このサイトではまだ使っていません。サイトの見せ方を工夫したくなったときの候補として紹介します。
プリフェッチ：リンク先を先に読み込んでおく
プリフェッチは、閲覧者がリンクをクリックする前に、リンク先のページを読み込んでおく機能です。クリックしたときにはページの準備ができているので、移動が速く感じられます。
astro.config.mjs に prefetch: true と書き、先読みしたいリンクに data-astro-prefetch を付けると使えます。先読みを始めるタイミングは、次の4つから選べます。
hover（標準）：リンクにマウスを乗せたとき、またはキーボードで選んだときtap：クリックする直前viewport：リンクが画面に入ったときload：ページを読み込み終わったとき
すべてのリンクを先読みの対象にする prefetchAll という設定もあります。
ページ遷移：ページを切り替えるときにアニメーションを付ける
astro:transitions から読み込める <ClientRouter /> をレイアウトの <head> に置くと、ページを移動するときに画面全体を読み込み直さず、アニメーションで切り替えるようになります。記事一覧のカードの画像が、記事ページの先頭の画像に広がるような見せ方もできます。
アニメーションだけが目的なら、CSS だけでページ遷移のアニメーションを付ける、ブラウザの標準機能を使う方法もあります。公式ドキュメントでは、こちらはサイトの動き方を変えないぶん手軽で、<ClientRouter /> はできることが多い方法として紹介されています。
URL の転送と多言語のサイト
redirects：URL を変えたときの転送
記事の URL を変えたときは、古い URL を開いた人を新しい URL へ転送する必要があります。Astro では、astro.config.mjs の redirects に古い URL と新しい URL の組を書いておけます。
ただし、このサイトのように静的なファイルだけを書き出す場合、Astro が作るのは「開いたらすぐ別の URL へ移動する HTML」（meta refresh）です。サーバーが「301：恒久的に移動した」と返す転送とは仕組みが違います。
このサイトは Cloudflare Workers で公開しているので、public/_redirects に転送のルールを書き、Cloudflare に 301 を返してもらっています。Cloudflare で公開しているなら、_redirects を使うほうが検索エンジンにも URL の変更が正しく伝わります。
/guide /articles/publish-with-cloudflare 301
/guide.html /articles/publish-with-cloudflare 301i18n：多言語のサイトを作る
日本語と英語のように、複数の言語でページを用意するための機能です。astro.config.mjs の i18n に使う言語（locales）と基本の言語（defaultLocale）を書き、src/pages/en/ のように言語ごとのフォルダにページを置きます。
標準の設定では、基本の言語のページは /about、ほかの言語のページは /en/about のような URL になります。言語ごとの URL は astro:i18n の getRelativeLocaleUrl() で作れるので、リンクを手で書き分ける必要はありません。
サイトが育ったら：サーバー側の処理に広げる
ここまでの機能は、どれもビルドのときに HTML などを作っておく使い方でした。Astro は標準ではすべてのページをビルドのときに作りますが、アダプターを入れると、一部のページだけを閲覧者がアクセスしたときにサーバーで作るようにもできます。
アダプターは、Astro のサイトを特定の配信サービスの上でサーバーとして動かすためのインテグレーションです。公式には Cloudflare、Netlify、Node.js、Vercel 向けのアダプターがあります。アダプターを入れたうえで、サーバーで動かしたいページに export const prerender = false と書くと、そのページだけがアクセスのたびに作られるようになります。
サーバーで動くようになると、次のような機能が使えます。
- Actions：フォームから送られた内容を、サーバーの関数で受け取る仕組み。送られた値が決まりに合っているかを、コンテンツコレクションと同じ書き方（Zod）で確かめられる
- サーバーアイランド：部品に
server:deferを付けると、ページの残りを先に表示しておき、その部品だけをあとからサーバーで作って差し込む。ログインした人の名前のように、人によって変わる部分に使う
注意点：サーバーで動くページは、Cloudflare の無料枠を使う
ビルドのときに作ったファイルを配信するだけなら、Cloudflare Workers の無料プランでも回数の上限はありません。サーバーで作るページは、アクセスのたびに Worker（Cloudflare の上で動くプログラム）が動くので、無料プランの「1日10万回まで」という上限に数えられます。サーバーで動かすのは、フォームの送信先のように本当に必要なページだけにしておくと安心です。
やりたいことから選ぶ Astro の機能
紹介した機能を、やりたいことの順に並べ直すと次のようになります。
| やりたいこと | 使う機能 | このサイト |
|---|---|---|
| ヘッダーやフッターを1か所で直したい | コンポーネント、レイアウト | 使っている |
| ファイルを置くだけでページを増やしたい | ファイルベースルーティング | 使っている |
| 記事を Markdown で書いて、一覧を自動で作りたい | MDX、コンテンツコレクション | 使っている |
| ボタンなどに動きを付けたい | script タグ（React などを使うならアイランド） | script タグだけ使っている |
| サイトマップや RSS を用意したい | @astrojs/sitemap、@astrojs/rss | 使っている |
| 写真やスクリーンショットを軽く表示したい | <Image />、<Picture /> | 使っていない |
| ページの移動を速く、なめらかにしたい | プリフェッチ、<ClientRouter /> | 使っていない |
| 複数の言語でページを用意したい | i18n | 使っていない |
| フォームの送信などをサーバーで処理したい | アダプター、Actions、サーバーアイランド | 使っていない |
表の上の5行は、ブログを作るならほぼ必ず使う機能です。このサイトも、Claude Code に移行を頼むときに「共通パーツはコンポーネントに、記事の一覧はコレクションから自動で作る」と条件を書いたので、この形になりました。Claude Code が作ったファイルが何をしているのか知りたくなったら、該当する節を見返してみてください。
下の4行は、必要になってから足せば間に合います。Claude Code に頼むときは、「Image コンポーネントで」「Actions で」のように機能の名前を書いておくと、Astro の標準の方法で作ってもらえます。
Claude Code と Cloudflare でサイトを公開するところから始めたい場合は、こちらの記事からどうぞ。
最初から読むClaude Code と Cloudflare でサンプルサイトを公開するまでClaude Code への1つの指示でサイトを生成し、GitHub 経由で Cloudflare Workers へ無料公開する最短手順と設定の勘所を解説します。