AstroPaperは、Astroで作られたブログ用のテーマです。掲げているのは最小限、レスポンシブ、アクセシブル、SEOフレンドリーの4つ。テンプレートを取ってきて設定ファイルを数行書き換えれば、もう自分のブログとして公開できます。このシリーズは、中身を理解したうえで手を入れられる状態になることを目標にしています。
Table of contents
Open Table of contents
このシリーズのねらい
すぐ使えるテーマではあるのですが、少し踏み込むと astro-paper.config.ts、content.config.ts、theme.css、Pagefind、Satoriによる画像生成と、いくつもの仕組みが顔を出します。何がどこに効くのか分からないままだと、ちょっと変えるのも怖くなります。
そこでこのシリーズは、その設定がどのファイルのどのコードに効くのかを毎回はっきりさせながら進めます。設定項目を並べるだけでは、テーマの動きは追えるようになりません。
対象読者と前提知識
想定している読者は次のような方です。
- HTMLとCSSの基本的な書き方が分かる
- Markdownで文章を書いたことがある
- npm / pnpm などでライブラリを入れた経験がある
- Astroについては、Astro徹底入門シリーズ程度の基礎知識があるとより読みやすい（なくても読めるように補足します）
TypeScriptについては、型注釈が読める程度で十分です。ReactやVueの知識は不要です。
学習ゴール
このシリーズを読み終えると、次のことができるようになります。
| ゴール | 対応する章 |
|---|---|
| AstroPaperが何を優先して作られたテーマなのか説明できる | 第1章 |
| プロジェクトを作成し、開発サーバーを起動できる | 第2章 |
| どのディレクトリに何があるかを把握して目的のファイルへたどり着ける | 第3章 |
astro-paper.config.ts の全項目を意図をもって設定できる | 第4章 |
| フロントマターを正しく書き、下書きや予約公開を使い分けられる | 第5章 |
| 記事をディレクトリやタグで整理し、URLを設計できる | 第6章 |
| 目次・引用ボックス・コードブロック・画像を使いこなせる | 第7章 |
| 配色を自分好みに変更できる | 第8章 |
| 検索・RSS・サイトマップの仕組みを理解して運用できる | 第9章 |
| OG画像とSEOメタ情報を制御できる | 第10章 |
| UI文言を日本語化し、多言語サイトの下地を作れる | 第11章 |
| ビルドしてホスティングサービスへ公開できる | 第12章 |
対象範囲・対象外
対象範囲
- AstroPaperの設計思想と技術スタック
- プロジェクト作成、開発サーバー、主要コマンド
- ディレクトリ構成と各ファイルの役割
astro-paper.config.tsによる設定- 記事のフロントマター、下書き、予約公開、タグ、注目記事
- Markdown表現（目次、コールアウト、コードブロック、画像）
- 配色テーマのカスタマイズ
- Pagefind検索、RSS、サイトマップ、robots.txt
- OG画像の動的生成とSEOメタ情報
- UI文言の翻訳と多言語対応
- ビルド、型チェック、デプロイ
対象外
以下は入門の範囲を超えるため、このシリーズでは扱いません。必要になった時点で公式ドキュメントを参照してください。
- Astro本体の詳細な機能解説（別シリーズで扱います）
- テーマのレイアウトを大きく作り替えるようなコンポーネント改造
- ホスティングサービスごとの詳細な設定手順や独自ドメインの取得
- CMSやデータベースとの連携
- テスト戦略やCI/CDパイプラインの構築
主要情報源
確認の基準日は2026年8月2日です。AstroPaperとAstroはどちらも更新が続いているため、実際に利用する際は必ず最新版のドキュメントとソースコードを確認してください。
ここで示すコードは、AstroPaperのテンプレート（package.json の version が 6.1.0、Astro 7系を前提）のソースを実際に開いて確認したものです。
| 情報源 | 参照範囲 |
|---|---|
| AstroPaper リポジトリ README | テーマの特徴、技術スタック、ディレクトリ構成、コマンド、ライセンス |
| AstroPaper 設定ガイド | astro-paper.config.ts の各項目と既定値 |
| AstroPaper 記事追加ガイド | フロントマターの各項目、下書き、目次、画像 |
| AstroPaper 配色カスタマイズガイド | theme.css のカラートークン |
テンプレート同梱ソース（src/types/config.ts、src/config.ts） | 設定の型定義と既定値の解決 |
テンプレート同梱ソース（src/content.config.ts、src/utils/） | コレクション定義、公開判定、URL生成 |
テンプレート同梱ソース（src/styles/、src/i18n/、src/pages/） | 配色トークン、UI文言、生成されるルート |
| Astro 公式ドキュメント | Astro本体の機能（コンテンツコレクション、画像、フォントなど） |
| Pagefind 公式サイト | 静的検索インデックスの仕組み |
| Satori リポジトリ | OG画像生成に使うHTML→SVG変換 |
記事一覧
- 01. AstroPaperとは何か：最小限で始めるブログテーマ
- 02. AstroPaperのインストールと開発サーバーの起動
- 03. AstroPaperのディレクトリ構成を読み解く
- 04. astro-paper.config.ts で設定する
- 05. AstroPaperで記事を書く：フロントマターと公開制御
- 06. AstroPaperで記事を整理する：ディレクトリ・URL・タグ
- 07. AstroPaperのMarkdown表現とアセットの扱い
- 08. AstroPaperの配色テーマをカスタマイズする
- 09. AstroPaperの検索・RSS・サイトマップ
- 10. AstroPaperでOG画像の自動生成とSEO
- 11. AstroPaperでUI文言の翻訳と多言語対応
- 12. AstroPaperのビルドとデプロイ
12章を5つのまとまりに分けました。どこまで進んだかの目印にしてください。
推定ボリュームと図解
1章あたりおおむね2,000〜4,000字です。通読には2〜3時間くらいかかると思います。
各章には理解を助けるためのMermaid図（SVGに変換して掲載）を用意しています。予定している図解は次のとおりです。あわせて、要点を1枚にまとめたインフォグラフィックも各章に3〜4枚ずつ挿入しています。
| 章 | 図解の内容 |
|---|---|
| 01 | AstroPaperを構成する3つの層 |
| 02 | プロジェクト作成から公開までの流れ |
| 03 | 主要ディレクトリと役割の対応 |
| 04 | 設定値が解決されて画面へ届くまで |
| 05 | 記事が一覧に表示されるかの判定フロー |
| 06 | ファイルパスから公開URLが決まる仕組み |
| 07 | Markdownが HTML になるまでの処理 |
| 08 | テーマ切り替えの動作順序 |
| 09 | 検索インデックスの生成と利用 |
| 10 | OG画像の決定ロジック |
| 11 | ロケールからUI文言が選ばれるまで |
| 12 | ビルドからデプロイまでの流れ |
それでは、01. AstroPaperとは何か：最小限で始めるブログテーマから始めましょう。