04. astro-paper.config.ts で設定する

シリーズ目次 前章: 03. AstroPaperのディレクトリ構成を読み解く 次章: 05. AstroPaperで記事を書く：フロントマターと公開制御

Table of contents

この章のねらい

astro-paper.config.ts は、AstroPaperで最初に編集するファイルです。全項目を並べて、それぞれが画面のどこに効くのかを見ていきます。

設定はどう解決されるのか

• astro-paper.config.ts：あなたが書くファイル。書かなかった項目は省略できる。
• src/types/config.ts：設定の型定義。エディタ上で入力補完が効き、綴りの誤りが検出される。
• src/config.ts：書かれていない項目に既定値を埋め、完全な設定オブジェクトを作る。テーマ内部はこちらを読む。

つまり、編集するのは astro-paper.config.ts だけで、src/config.ts は触りません。

ファイルの骨格

import { defineAstroPaperConfig } from "./src/types/config";

export default defineAstroPaperConfig({
  site: {
    /* ... */
  },
  posts: {
    /* ... */
  },
  features: {
    /* ... */
  },
  socials: [],
  shareLinks: [],
});astro-paper.config.ts

defineAstroPaperConfig は、設定オブジェクトをそのまま返すだけの関数です。実行時には何もしませんが、これで包むことでエディタが期待される形を認識し、入力補完と型チェックが効くようになります。

site は必須、残りの4グループは省略できます。5つが何を受け持つのかを先に掴んでおいてください。

site：サイトの基本情報

必須のグループです。

site: {
  url: "https://example.com/",
  title: "サンプルブログ",
  description: "Web開発について学んだことを書いています。",
  author: "sample-author",
  profile: "https://example.com/about/",
  ogImage: "default-og.jpg",
  lang: "ja",
  timezone: "Asia/Tokyo",
  dir: "ltr",
},astro-paper.config.ts

必須の4項目は、それぞれ1か所ではなく複数の出力先へ同時に届きます。

url は正確に

url はSEOに直結します。ここに書いたURLをもとに、各ページの正規URL（<link rel="canonical">）やサイトマップが作られます。間違ったURLを入れると、検索エンジンが別サイトの内容だと判断してしまう可能性があります。

ogImage はファイル名のみ

ogImage には public/ 直下のファイル名だけを書きます。/ や .. を含めるとビルド時にエラーになります。これは、意図しないファイルを外部へ公開してしまうのを防ぐための制限です。

timezone の効き方

記事の日付表示に使われます。"Asia/Tokyo" を設定すると、フロントマターに書いた協定世界時（UTC）の日時が日本時間に変換されて表示されます。IANAタイムゾーン名（Asia/Tokyo、America/New_York など）を使ってください。

googleVerification

設定ファイルに直接書くこともできますが、環境変数 PUBLIC_GOOGLE_SITE_VERIFICATION からも読み込まれます。設定ファイルの値が優先され、なければ環境変数が使われます。

site: {
  // ...
  googleVerification: "<your-verification-value>",
},astro-paper.config.ts

posts：記事一覧の挙動

posts: {
  perPage: 10,
  perIndex: 5,
  scheduledPostMargin: 15 * 60 * 1000,
},astro-paper.config.ts

scheduledPostMargin とは

未来の日時を設定した記事は、その時刻まで公開されません。ただし、ビルドしてから配信されるまでには時間差があります。そこで「公開時刻の少し手前でビルドした場合も、公開済みとして扱う」猶予がこの項目です。

既定の15分は 15 * 60 * 1000 ミリ秒と書かれています。計算式のまま残しておくと、後から読んで意図が分かります。

3つの数値が、それぞれ別の画面と別のタイミングを受け持っています。

features：機能のON/OFF

features: {
  lightAndDarkMode: true,
  dynamicOgImage: true,
  showArchives: true,
  showBackButton: true,
  editPost: { enabled: false },
  search: "pagefind",
},astro-paper.config.ts

editPost の書き方

有効にする場合は、編集ページのURLも一緒に指定します。

editPost: {
  enabled: true,
  url: "https://github.com/<your-org>/<your-repo>/edit/main/",
},astro-paper.config.ts

型定義では、enabled: true のときだけ url が必須になるよう定義されています。片方だけ書くと型エラーになるため、書き忘れを防げます。

無効にしたときの動き

showArchives や search を false にすると、リンクが消えるだけでなく、そのURLへ直接アクセスしても404ページが表示されます。/archives/ と /search/ のコードには、設定を見て404へ振り替える処理が入っています。

dynamicOgImage を false にするなら、画像を先に用意してください。public/{site.ogImage} のファイルが存在しないとビルドが失敗します。自動生成に頼らないのであれば、必ず画像を用意してください。詳しくは第10章で扱います。

6つのスイッチの既定値と、切り替えたときの影響をまとめると次のようになります。

socials：SNSリンク

ヘッダーとフッターに並ぶアイコンリンクです。

socials: [
  { name: "github", url: "https://github.com/<your-org>" },
  { name: "mail", url: "mailto:<your-address>" },
],astro-paper.config.ts

name はアイコンのファイル名と一致している必要があります。src/assets/icons/socials/github.svg があるから "github" と書ける、という関係です。存在しない名前を書くとビルドが失敗します。

空の配列（または未設定）にすると、SNSリンクの領域そのものが表示されなくなります。

shareLinks：記事の共有ボタン

記事詳細ページの下部に出る共有ボタンです。

shareLinks: [
  { name: "x", url: "https://x.com/intent/post?url=" },
  { name: "facebook", url: "https://www.facebook.com/sharer.php?u=" },
  { name: "mail", url: "mailto:?subject=See%20this%20post&body=" },
],astro-paper.config.ts

url は「記事のURLを末尾に付け足せば共有できる」形にしておきます。テーマ側が末尾に記事URLを連結します。

socials と同様に、空にすれば共有ボタンは表示されません。

設定を変更したら

astro-paper.config.ts を保存すると、開発サーバーは自動で再読み込みします。もし反映されない場合は、一度サーバーを止めて起動し直してください。

型エラーは pnpm astro check で確認できます。

pnpm astro check

最小構成の例

必須項目だけを書いた最小の設定は次のようになります。

import { defineAstroPaperConfig } from "./src/types/config";

export default defineAstroPaperConfig({
  site: {
    url: "https://example.com/",
    title: "サンプルブログ",
    description: "学んだことを記録しています。",
    author: "sample-author",
  },
});astro-paper.config.ts

これだけで、残りはすべて既定値で動きます。この形から始めて、要る項目だけ足してください。

要点

• 編集するのは astro-paper.config.ts のみで、src/config.ts は既定値を埋める内部ファイルである。
• site グループだけが必須で、posts / features / socials / shareLinks は省略できる。
• site.url は正規URL・RSS・サイトマップの基準になるため、公開先と正確に一致させる。
• features の項目を false にすると、リンクが消えるだけでなく該当URLも404になる。
• socials と shareLinks の name は、src/assets/icons/socials/ のSVGファイル名と一致している必要がある。

参考資料

• AstroPaper 設定ガイド — 各設定項目の公式説明
• AstroPaper リポジトリ README — Google Site Verificationの設定例
• テンプレート同梱ソース src/types/config.ts — 設定の型定義とコメント
• テンプレート同梱ソース src/config.ts — 既定値の適用ロジック
• Astro: Environment Variables — PUBLIC_ 接頭辞付き環境変数の扱い

シリーズ目次 前章: 03. AstroPaperのディレクトリ構成を読み解く 次章: 05. AstroPaperで記事を書く：フロントマターと公開制御