シリーズ目次 前章: 02. AstroPaperのインストールと開発サーバーの起動 次章: 04. astro-paper.config.ts で設定する
Table of contents
Open Table of contents
この章のねらい
プロジェクトを作ると、ディレクトリとファイルがどっと現れます。全部覚える必要はありません。よく触る場所、たまに触る場所、基本的に触らない場所の3つに分けて押さえておけば、必要なときに目的地へ行けます。
全体像
READMEに記載されている構成を、コメント付きで示します。
/
├── public/ # そのまま配信されるファイル
│ ├── pagefind/ # ビルド時に自動生成される検索索引
│ ├── favicon.svg
│ └── default-og.jpg
├── src/
│ ├── assets/
│ │ ├── icons/ # UIアイコン（SVG）
│ │ └── images/ # 記事などで使う画像
│ ├── components/ # 共通の部品
│ ├── content/
│ │ ├── pages/
│ │ │ └── about.md # 固定ページ
│ │ └── posts/ # ブログ記事はここ
│ ├── i18n/ # UI文言（多言語）
│ ├── layouts/ # ページの骨組み
│ ├── pages/ # URLに対応するページ
│ ├── scripts/ # ブラウザで動くスクリプト
│ ├── styles/ # CSS
│ ├── types/ # 型定義
│ ├── utils/ # 補助的な処理
│ ├── config.ts # 設定の既定値を適用する
│ └── content.config.ts # コンテンツの定義とスキーマ
├── astro-paper.config.ts # あなたが編集する設定
└── astro.config.ts # Astro本体の設定編集する頻度で3つに束ねると、全体像が掴めます。
よく触る場所
src/content/posts/
ブログ記事のMarkdownファイルを置くディレクトリです。日常的にもっとも触る場所です。
ファイルを追加するだけで記事が増え、サブディレクトリを作ればURLにもそれが反映されます。詳しくは第6章で扱います。
astro-paper.config.ts
サイト名、URL、著者名、1ページあたりの記事数、機能のON/OFF、SNSリンクなどをまとめた設定ファイルです。プロジェクトルート（一番上の階層）にあります。
利用者が編集するのはここだけで済むように、という方針で用意されたファイルです。次章で全項目を扱います。
src/content/pages/about.md
このサイトについて、のような固定ページの本文です。記事一覧には並ばず、専用のURLで表示されます。テンプレートには about.md が1つ入っています。
src/styles/theme.css
配色を決めるCSSファイルです。7つの色トークンを書き換えるだけで、サイト全体の見た目が変わります。第8章で詳しく扱います。
たまに触る場所
src/i18n/
画面に出る英語のUI文言（「Recent Posts」「Search」など）がまとまっています。
src/i18n/
├── index.ts # ロケールに応じて文言を選ぶ
├── format.ts # {{変数}} の差し替え
├── types.ts # 文言の型定義
└── lang/
└── en.ts # 英語の文言日本語化したい場合は lang/ja.ts を追加します。手順は第11章で説明します。
public/
ここに置いたファイルは、加工されずにそのままの名前で公開されます。public/favicon.svg は /favicon.svg としてアクセスできます。
| ファイル | 役割 |
|---|---|
favicon.svg | ブラウザのタブに出るアイコン |
default-og.jpg | SNS共有時に使われる既定の画像 |
pagefind/ | ビルド時に生成される検索索引 |
pagefind/ は自動生成物なので、手で編集しないでください。
src/assets/
public/ と違い、こちらに置いた画像はAstroが最適化します。サイズ変更も形式変換も自動なので、記事で使う画像はこちらに置いてください。
2つのディレクトリの違いは、公開されるまでに加工が入るかどうか。それだけです。
icons/ には IconRss.svg や IconSearch.svg といったUIアイコンが入っています。これらはTabler Iconsのアイコンで、Astroのコンポーネントとして直接読み込めます。
---
import IconRss from "@/assets/icons/IconRss.svg";
---
<IconRss width={20} height={20} />
@/はsrc/を指す別名（エイリアス）です。深い階層から../../../と書かずに済むよう、tsconfig.jsonに設定してあります。
基本的に触らない場所
テーマの本体にあたる部分です。読むぶんには勉強になりますが、書き換えるとテーマの更新を取り込めなくなります。
src/pages/
URLとファイルが対応する、Astroの中心的なディレクトリです。
| ファイル | 生成されるURL |
|---|---|
index.astro | / |
about.astro | /about/ |
search.astro | /search/ |
404.astro | 存在しないURLへのアクセス時 |
posts/[...page].astro | /posts/、/posts/2/ … |
posts/[...slug]/index.astro | /posts/記事のパス/ |
tags/index.astro | /tags/ |
tags/[tag]/[...page].astro | /tags/タグ名/ |
archives/index.astro | /archives/ |
rss.xml.ts | /rss.xml |
robots.txt.ts | /robots.txt |
og.png.ts | /og.png |
角かっこ [...] は、ここが可変という意味です。[...slug] なら /posts/astro-paper/01-what-is-astro-paper/ のように複数階層をまとめて受け取れます。
なお src/pages/ の中でも、_ から始まるディレクトリ（_components/、_utils/）はURLになりません。そのページ専用の部品を近くに置くための仕組みです。
名前の付け方は3通りあります。そのままURLになるもの、可変部分になるもの、URLにならないもの。
src/layouts/
| ファイル | 役割 |
|---|---|
Layout.astro | 全ページ共通の <html> 〜 <head>。メタ情報、フォント、テーマ切り替えの初期化 |
PostLayout.astro | 記事詳細用。Layout.astro に記事向けのメタ情報を足したもの |
src/components/
複数のページで使い回す部品です。
| ファイル | 役割 |
|---|---|
Header.astro / Footer.astro | ヘッダーとフッター |
Card.astro | 一覧に並ぶ記事1件分の表示 |
Datetime.astro | 日付の表示（タイムゾーン変換込み） |
Pagination.astro | ページ送り |
Tag.astro | タグのラベル |
Socials.astro | SNSリンクの並び |
Breadcrumb.astro | パンくずリスト |
Main.astro | 一覧系ページの見出しと本文枠 |
LinkButton.astro | ボタン風のリンク |
ResponsiveTable.astro | 横幅の広い表を横スクロールさせる枠 |
GoogleAnalytics.astro | 計測タグの読み込み |
src/utils/
テーマの動作を支える小さな関数群です。挙動の理由を追いたくなったら、ここを開きます。
| ファイル | 役割 |
|---|---|
postFilter.ts | 下書き・予約公開を判定して記事を絞り込む |
getSortedPosts.ts | 更新日時の新しい順に並べる |
getPostPaths.ts | ファイルパスから公開URLを組み立てる |
getUniqueTags.ts | 重複を除いたタグ一覧を作る |
slugify.ts | 文字列をURL向けの表記へ変換する |
withBase.ts | 公開時のパス接頭辞を付け外しする |
resolveDefaultOgImagePath.ts | 既定のOG画像パスを決める |
toTransitionName.ts | 画面遷移アニメーション用の名前を作る |
getFontPathByWeight.ts | OG画像生成に使うフォントを探す |
src/config.ts と src/content.config.ts
紛らわしい名前ですが、役割は別物です。
src/config.ts：astro-paper.config.tsに書かれた値を読み込み、書かれていない項目に既定値を埋める。テーマ内部からはこちらを参照する。src/content.config.ts：記事と固定ページの取り込み範囲とフロントマターの形式を定義する。
迷ったときの早見表
| やりたいこと | 触る場所 |
|---|---|
| 記事を追加したい | src/content/posts/ |
| サイト名やURLを変えたい | astro-paper.config.ts |
| 配色を変えたい | src/styles/theme.css |
| 「このサイトについて」を書き換えたい | src/content/pages/about.md |
| 画面の英語表記を日本語にしたい | src/i18n/lang/ |
| ファビコンを差し替えたい | public/favicon.svg |
| 記事本文の文字サイズや余白を調整したい | src/styles/typography.css |
| ヘッダーのメニューを変えたい | src/components/Header.astro |
上の6つを覚えておけば、テーマ本体へ踏み込まずに済みます。
要点
- 日常的に触るのは
src/content/posts/、astro-paper.config.ts、src/styles/theme.cssの3か所だけと言っていい。 public/は加工せずそのまま配信され、src/assets/はAstroが最適化する。画像は原則src/assets/に置く。src/pages/のファイル構成がそのままURLになり、_で始まるディレクトリはURLにならない。src/config.tsは既定値を埋める内部設定、src/content.config.tsは記事の取り込み範囲とフロントマター定義であり、役割が異なる。src/utils/の各関数を把握しておくと、並び順や公開判定の理由を自分で追える。
参考資料
- AstroPaper リポジトリ README — 公式のディレクトリ構成図
- Astro: Project Structure —
src/pages、public、src/assetsの役割 - Astro: Routing — ファイル名とURLの対応、
[...slug]の意味 - Astro: Images —
src/assetsとpublicの使い分け - Tabler Icons — 同梱アイコンの出典
シリーズ目次 前章: 02. AstroPaperのインストールと開発サーバーの起動 次章: 04. astro-paper.config.ts で設定する