設定ファイル

サイトのメタデータやコンテンツソースから、個々の機能の設定ガイドへと続くリンクまで、blume.config.ts のすべてのオプション。

Blume はプロジェクトルートの blume.config.ts を読み込みます。設定を defineConfig でラップすると、オートコンプリートと型チェックが有効になります。すべてのフィールドは任意で、適切なデフォルト値が用意されています。

import { defineConfig } from "blume";

export default defineConfig({
  title: "My Docs",
  description: "Documentation for my project.",
});

完全な例

最もよく使われるオプションを一通り含んだ、より広範な例です（残りは各機能のガイドを参照してください）:

import partytown from "@astrojs/partytown";
import { defineConfig } from "blume";
import { orama } from "blume/search";

export default defineConfig({
  // Site
  title: "My Docs",
  description: "Documentation for my project.",
  logo: "/logo.svg",

  // Astro integrations — installed and versioned by this site
  integrations: [partytown()],

  // Content
  content: {
    root: "docs",
  },

  // Theme — see the Theming guide
  theme: {
    accent: "teal",
    radius: "md",
    mode: "system",
  },

  // Search — an adapter from "blume/search"; see the Search guide
  search: orama(),

  // Markdown features
  markdown: {
    imageZoom: true,
    externalLinks: false, // open https:// links in a new tab
    code: {
      icons: true, // language icon in the code-block header
      wrap: false, // wrap long lines instead of scrolling
      theme: {
        light: "github-light", // bundled name or custom Shiki theme object
        dark: "github-dark",
      },
    },
  },

  // Agents — llms.txt, MCP, the AI catalog; see the Discoverability section
  agents: {
    llmsTxt: true,
    // AI Catalog / ARD manifest at /.well-known/ai-catalog.json (needs deployment.site)
    catalog: true,
    // Your site's agent skill at /skill.md (needs deployment.site)
    skillMd: true,
    // MCP server (needs server output)
    mcp: {
      enabled: false,
      route: "/mcp",
    },
  },

  // SEO — OG images, feeds, sitemap, structured data; see the Discoverability section
  seo: {
    og: { enabled: true },
    rss: { enabled: true, types: ["blog", "changelog"] },
    sitemap: true,
    robots: true,
    structuredData: true,
  },

  // Deployment — a static build here; see the Deployment guide for host adapters
  deployment: {
    site: "https://docs.example.com",
  },
});

サイト

ロゴ

logo に SVG を指定すると Blume がインライン展開するため、currentColor を使ったロゴはライトテーマとダークテーマに自動で追従します:

logo: "/logo.svg",

SVG はプロジェクトルートまたは public/ に配置できます。ブランドはマーク（image）とワードマーク（text）で構成され、オブジェクト形式ならそれぞれを個別に設定できます:

logo: {
  image: "/logo.svg", // string, or { light, dark, alt } for themed raster art
  text: "Acme",       // wordmark beside the mark
  href: "/",          // overrides the brand link (defaults to "/")
},

image は省略形と同じ値を取ります。単一のパス、またはライト/ダークで別々のアートワークを使う場合は { light, dark, alt } です（ラスター画像は public/ に配置する必要があります）。

href はタブのパスと同じく、デフォルトロケールを基準にしたパスです。多言語サイト では、読者のロケールがそのルートを提供している場合、ブランドリンクはそのロケールに移動します（/en/… 配下では / が /en になります）。そのため、ロゴをクリックしても読んでいた言語から離れることはありません。デフォルトロケールだけが提供するルート — カスタムページ や生成されたチェンジログのインデックスなど — は、404 になってしまうローカライズ済み URL を指す代わりに、元のパスを維持します。絶対 URL はそのまま使われます。

text はマークとは独立してワードマークを制御します:

• text を省略すると、ブランドにはサイトの title が使われます（デフォルト）。
• text: "" を設定するとマークのみを表示します。ロゴ画像にすでにワードマークが含まれている場合に便利です。その場合、スクリーンリーダーはブランドリンクを画像の alt で読み上げ、alt がなければサイトの title で読み上げます。
• image なしで text を設定すると、テキストのみのロゴになります。

ファビコン

ファビコンのオプションはありません。Blume は Next.js と同じようにファイル名から自動検出します。icon または favicon というファイル（.svg、.png、.ico）をプロジェクトルートまたは public/ ディレクトリに置くと、ブラウザのタブアイコンになります:

my-docs/
├─ blume.config.ts
├─ icon.png          ← picked up automatically
└─ docs/

複数存在する場合は SVG が PNG より、PNG が ICO より優先され、ルート直下のファイルよりも public/ 内のファイルが優先されます。アイコンが見つからない場合、Blume は自身のマークにフォールバックします。

暗い色のマークは暗いブラウザ UI の中では見えなくなってしまうため、ダークモード用に 2 つ目のファイルを用意できます。アイコンファイルの -dark 兄弟ファイル — 同じ名前・同じディレクトリで、拡張子の前に -dark を付けたもの（icon.png → icon-dark.png）— を追加すると、Blume は prefers-color-scheme メディアクエリを介して両方のアイコンを出力し、あわせてアイコンのメディアクエリを無視するブラウザやクローラー向けにライト用のプレーンなタグも出力します:

my-docs/
├─ blume.config.ts
├─ icon.png          ← light mode
├─ icon-dark.png     ← dark mode
└─ docs/

使われるのは Blume が選択したアイコンの兄弟ファイルだけです。名前が異なる -dark ファイルは無視されるため、無関係なファイルが誤ってマークと組み合わされることはありません。ダーク用ファイルは任意で、アイコンが 1 つだけの場合、Blume はこれまでどおり単一のタグを出力します。Blume 自身のフォールバックマークは両方のバリエーションを備えています。

Apple タッチアイコン

サイトをホーム画面に追加したときに iOS が使うアイコンも、同じ方法で検出されます。apple-icon というファイル（.png、.jpg、.jpeg）— あるいは、多くのファビコン生成ツールが出力する名前である apple-touch-icon.png — をプロジェクトルートまたは public/ ディレクトリに置くと、Blume が <link rel="apple-touch-icon"> を設定します。デフォルトはありません。ファイルが見つからない場合、タグは出力されません。

my-docs/
├─ blume.config.ts
├─ apple-icon.png     ← picked up automatically
└─ docs/

このファイルはプロジェクトルートではなく public/ に置いてください。ルート直下のアイコンに対して Blume が使うインラインのデータ URI は iOS では無視されるため、public/ に置いたファイル（/apple-icon.png で配信されます）だけが確実にホーム画面に反映されます。ファビコンとは異なり、ここでは -dark 兄弟ファイルはありません。iOS はホーム画面アイコンのメディアクエリを無視するため、ダーク用のバリエーションを配信することはそもそもできないからです。

バナー

ヘッダーの上にサイト全体のお知らせバーを表示します。文字列を渡すか、リンクと閉じるボタンを含むオブジェクトを渡します:

banner: "Docs are in beta — expect changes.",

banner: {
  content: "Version 2.0 is here!",
  link: { text: "Read the release notes", href: "/changelog" },
  dismissible: true,
  id: "v2",
},

dismissible を有効にすると、バーに閉じるボタンが表示され、それ以降その訪問者には非表示のままになります。閉じた状態を記録するキーはデフォルトで本文テキストになるため、メッセージを編集するとバナーが再び表示されます。編集後も閉じたままにするには、安定した id を設定してください。

多言語 サイトでは、content とリンクの text に、ロケールコードからテキストへのマップを指定することもできます。各ページには自身のロケールのエントリが表示され、ない場合はデフォルトロケールのエントリにフォールバックします。また、読者のロケールがそのページを提供している場合、リンクはそのロケールに移動します:

banner: {
  content: { en: "Version 2.0 is here!", fr: "La version 2.0 est là !" },
  link: {
    text: { en: "Read the release notes", fr: "Lire les notes de version" },
    href: "/changelog",
  },
},

翻訳されたバナーでは、閉じた状態を記録するキーにデフォルトロケールのテキストが使われるため、一度閉じればすべての言語で非表示になります。

フッター

すべてのページの末尾にはフッターが表示されます。ヘッダーと同じ高さの 1 行で、片側にリンク、もう片側にソーシャルプロフィールのアイコンが並び、その間の中央に著作権表示が置かれます。Blume がソーシャルプロフィールとリポジトリへのリンクを置くのはフッターだけなので、github のリポジトリが設定されている場合は、常にアイコンの先頭に表示されます。残りは footer で追加します:

footer: {
  copyright: "© 2026 Acme, Inc.",
  links: [
    { label: "Pricing", href: "https://acme.dev/pricing" },
    { label: "Changelog", href: "/changelog" },
    { label: "Blog", href: "https://acme.dev/blog" },
  ],
  socials: {
    x: "https://x.com/acme",
    discord: "https://discord.gg/acme",
  },
},

copyright はプレーンテキストなので、© ではなく © そのものを記述してください。年を常に最新に保つには、テンプレートリテラルを使います: `© ${new Date().getFullYear()} Acme, Inc.`。links は記述した順に表示されます。内部リンクはルートにマウントされているものとして記述してください。外部リンクは新しいタブで開きます。多言語 サイトでは、copyright と label にそれぞれロケールコードからテキストへのマップを指定でき、読者のロケールがそのページを提供している場合、内部リンクはそのロケールに移動します。socials はプラットフォームをそのプロフィール URL に対応付けるもので、アイコンは記述した順に表示されます。使用できるプラットフォームは bluesky、discord、facebook、github、hacker-news、instagram、linkedin、medium、podcast、reddit、slack、telegram、threads、website、x、youtube です。github のソーシャルを指定すると、リポジトリリンクが置き換えられます。そのリンクを非表示にするには navigation.repo を使ってください。

著作権表示、リンク、プロフィール、リポジトリのいずれもないサイトには、フッターは表示されません。PageLayout 上に構築したカスタムページでも、レイアウト自身の footer スロットを埋めない限りフッターが表示されます。フッターを完全に置き換えるには、Footer レイアウトスロット を上書きしてください。

コンテンツ

コンテンツの置き場所と、Blume がそれをどう検出するかです。ファイルがどのようにルートになるかは ページ を参照してください。

content: {
  root: "docs",
}

静的アセットは public/ に置きます。public/logo.png にあるファイルは /logo.png で配信されるため、![](/images/create.png) のような参照は public/images/create.png に解決されます。相対パスで参照される画像（![](./diagram.png)）はコンテンツの隣に配置し、ビルド時に最適化されます。

画像

相対パスで参照されるローカル画像は、ビルド時に自動的に最適化されます。圧縮され、WebP に変換され、読み込み中にレイアウトがずれないよう本来の width/height 属性が付与されます。設定は不要です。執筆時のガイダンスは リンクと画像 を参照してください。

リモート画像はデフォルトでは手を加えずに配信されます。Blume にビルド時のダウンロードと最適化も行わせるには、そのホストを許可してください:

image: {
  domains: ["cdn.example.com"],
  remotePatterns: [{ protocol: "https", hostname: "**.example.com" }],
}

フロントマター

ページのフロントマターは厳格に検証され、未知のキーがあるとビルドが失敗するため、タイプミスを早期に発見できます。プロジェクト固有のメタデータ（担当者、レビュー日など）を持たせるには、追加のキーを frontmatter.extend の下に宣言し、それぞれに用意したスキーマを対応付けます:

import { defineConfig } from "blume";
import { z } from "zod";

export default defineConfig({
  frontmatter: {
    extend: {
      owner: z.string(),
      reviewedAt: z.coerce.date().optional(),
    },
  },
});

任意の Standard Schema ライブラリが利用できます — Zod（プロジェクトがインストールしているバージョンを問わず）、Valibot、ArkType など。拡張の外側のキーは引き続き厳格に検証されるため、タイプミスの検出はこれまでどおりです。検証のセマンティクスについては カスタムキー を参照してください。

extend の下のキーはサイト全体に適用されます。特定のコンテンツタイプのページにだけキーを必須にしたい場合 — RFC の status、ランブックの service など — は、代わりに content.types の下でタイプごとに宣言してください:

import { defineConfig } from "blume";
import { z } from "zod";

export default defineConfig({
  content: {
    types: {
      rfc: {
        facets: ["domain", "status"],
        frontmatter: {
          domain: z.string(),
          status: z.enum(["draft", "review", "enforced"]),
        },
      },
    },
  },
});

1 つのキーはサイト全体かタイプごとのどちらかで宣言でき、両方はできません。スコープがどう解決されるかは タイプごとのキー を参照してください。

facets は、その値がフィルタ可能なメタデータになるカスタムキーを指定します。これらは検索ドキュメント（blume-search.json と MCP インデックス）に付随し、MCP ツール はそれらに対して照合を行う filters 入力を受け付けます。そのため、エージェントは例えば architecture ドメインの enforced な RFC だけを取得できます。各ファセットは宣言済みのカスタムキー（タイプごと、またはサイト全体）である必要があり、ファセットになるのは文字列（あるいは文字列化された数値・真偽値）の値のみです。

GitHub

github で Blume にリポジトリを指定します。これはフッターの リポジトリリンク と、Edit on GitHub の ページアクション を有効にします:

github: {
  owner: "acme",
  repo: "docs",
}

GitHub Enterprise

リポジトリが GitHub Enterprise インスタンスにあるドキュメントでは host を設定します。すると、リポジトリから導出されるすべてのリンク — ヘッダーのマーク、編集リンク、エージェントマニフェスト — が、公開サイトではなくそのインスタンスを指すようになります:

github: {
  host: "https://github.acme.com",
  owner: "acme",
  repo: "docs",
}

<GithubInfo> が問い合わせる REST API のベースは host から導出されます。データレジデンシーを備えた Enterprise Cloud テナント（acme.ghe.com）はその api. サブドメインから配信され、それ以外のホストは Enterprise Server（/api/v3）として扱われます。インスタンスがそれ以外の場所にある場合は、api を明示的に設定してください。

最終更新日

各ページの下部に「Last updated on …」の行を表示します。デフォルトは無効です。lastModified を "git" に設定すると、各ページの日付が git 履歴から算出されます:

lastModified: "git",

git ソースは各ファイルに触れた最新のコミットを読み取るため、モノレポを含むあらゆる git リポジトリで機能し、ビルド時にリポジトリの履歴が必要です。git log --follow と同様にリネームも追跡します。page.md を page.mdx にリネームしたり、同じコンテンツルート配下の別のフォルダにファイルを移動したりしても、そのコミットで内容が変わっていなければページの日付は維持されます。リネームと同時にファイルを編集した場合は、そのコミットの日時がページの日付になります。コンテンツルートの外からファイルを移動してきた場合も同様です。CI プラットフォームは通常シャロークローンでチェックアウトするため、ほとんどの日付が黙って失われます（その場合、ビルドは BLUME_SHALLOW_GIT_HISTORY で警告します）。Vercel では VERCEL_DEEP_CLONE=true 環境変数を設定し、actions/checkout では fetch-depth: 0 を設定してください。ページ自身の lastModified フロントマターが常に優先されるので、日付を固定したい場合や、まだコミットされていないファイルに便利です:

---
title: My page
lastModified: 2026-06-20
---

有効にすると、この日付はページの構造化データに schema.org の dateModified としても出力されます。

日付フォーマット

「Last updated」のスタンプと チェンジログ のタイムラインは、どちらも同じ dateFormat を通して日付を描画するため、表記が揃います。日付は常にサイトのロケールで描画され、dateFormat は形式を制御します。デフォルトは長い形式です（July 21, 2026、2026年7月21日）:

dateFormat: { dateStyle: "long" },

dateFormat は Intl.DateTimeFormat のオプションへのパススルーです。長さを指定するには dateStyle のプリセットを使います:

dateFormat: { dateStyle: "medium" },

あるいは、2026/07/21 のような数値中心のハウススタイルにするには、個別のコンポーネントフィールドを使います:

dateFormat: { year: "numeric", month: "2-digit", day: "2-digit" },

timeZone、calendar、numberingSystem は形式を変えません。これらだけを設定した dateFormat では、長い形式のままになります。

SEO とエージェント

メタデータ、Open Graph 画像、RSS フィード、JSON-LD、サイトマップ、robots.txt は seo の下にまとまっています。llms.txt、生の Markdown、JSON API、MCP サーバー、ディスカバリーマニフェストは agents の下です。どちらも 発見可能性 セクションでページごとに解説しており、そこでは検索エンジンと AI エージェントを、同じ機械可読レイヤーに対する 2 つのオーディエンスとして扱っています。読者向けのモデル機能 — アシスタントと Open in chat アクション — は ai の下にあります。

seo: {
  og: { enabled: true },
  rss: { enabled: true, types: ["blog", "changelog"] },
  sitemap: true,
  robots: true,
  structuredData: true,
}

これらは、完全な URL を得るために絶対パスの deployment.site と組み合わせると最も効果的です。

目次

このページの見出し一覧はデフォルトで有効になっており、H2〜H3 の見出しを掲載します。toc で無効にしたり、見出しの範囲を変更したりできます:

export default defineConfig({
  toc: false, // hide it everywhere
});

あるいは、見出しの範囲を絞り込みます:

export default defineConfig({
  toc: { minHeadingLevel: 2, maxHeadingLevel: 4 },
});

ページのフィードバック

各ドキュメントページの末尾には「Was this page helpful?」の評価が表示されます。デフォルトで有効になっており、feedback を false に設定するとすべてのページで非表示になります:

export default defineConfig({
  feedback: false,
});

読者の回答は、helpful（"yes" または "no"）、path、title を含む feedback の カスタムイベント として、イベント API を持つ設定済みのすべてのアナリティクスアダプターを通じて送信されます。あわせて window 上の blume:track イベントとしても送出されます。Fathom、Microsoft Clarity、Hotjar はイベント名だけを受け取り、プロパティは受け取らないため、評価の件数は数えられますが、「はい」と「いいえ」を区別できません。アナリティクスアダプターがない場合、回答はどこにも記録されません。また、Cookie の同意 が有効な場合、評価はアナリティクスを許可した読者にのみ表示されます。それ以外の読者から回答を受け取っても、送信先がないためです。質問文とお礼のテキストは UI 文字列なので、i18n.ui で翻訳できます。

記述式のフィードバック

「はい」か「いいえ」以上の声を聞くには、コメントを有効にします。読者がページを評価すると、良かった点や不足している点を書き込める入力欄が表示されます:

export default defineConfig({
  feedback: { comments: true },
});

コメントは feedback_comment イベントとして送信され、評価と同じ helpful、path、title に加えて、読者の comment（最大 1,000 文字）を含みます。評価と同じアダプターを通じて送信されるため、コメントはイベントを確認している場所で読めます。プロバイダーはプロパティ値の長さに上限を設けているため、長いコメントは途中で切り詰められて届くことがあります。Google Analytics は 100 文字、Mixpanel は 255 バイト（日本語のように 1 文字に複数バイトを使う文字体系では、文字数はそれより少なくなります）まで保持し、Vercel Web Analytics は 255 文字までの値を受け付けます。一方、PostHog と Segment はコメントを全文そのまま渡します。Fathom、Clarity、Hotjar にはコメントのテキストがまったく届きません。Plausible は個々のコメントを一覧表示せず、同一の値をグループ化するため、コメントよりも評価に向いています。読者は入力欄に何でも書き込めるため、コメントには個人情報が含まれている可能性があるものとして扱ってください。

入力欄のラベルとボタンも UI 文字列です（feedback.comment と feedback.send）。

機能ごとのオプション

以下にはそれぞれ専用のガイドがあります。設定フィールドがその入口です:

優先順位

設定は優先度の低いものから高いものへと解決されるため、必要な部分だけを上書きすれば済みます: