コンテンツにスキップ
Blume
日本語
EnglishDeutschहिन्दी日本語Português
Esc
↑↓移動↵開く⌘Jプレビュー
このページの内容

ナビゲーション

Blume はファイルからサイドバーを構築し、フロントマター、フォルダーの meta、または設定で調整できるようにします — パンくずリストとアウトラインもそれに追従します。

Blume はファイルシステムからサイドバーを構築し、あとはページ単位、フォルダー単位、または 1 つの明示的な設定で、好きなだけ（あるいは最小限に）調整できるようにします。パンくずリスト、前後のリンク、ページ内アウトラインはすべて同じモデルから導かれるため、配線する作業は一切ありません。

生成されるサイドバー

デフォルトでは、サイドバーはコンテンツツリーをそのまま反映します。

  • フォルダーはグループに、ファイルはページになります
  • ページのラベルはフロントマターの title、グループのラベルは人間向けに整形されたフォルダー名です
  • 項目は数値プレフィックス順、次にアルファベット順に並び、フォルダーの index ページが最初に来ます

多くのサイトではこれで十分です — 以下はすべてオプトインです。

ページのラベル、アイコン、バッジ

個々のページがサイドバーにどう表示されるかは、フロントマターの sidebar 以下で調整します。

sidebar:
  label: Quickstart # override the title in the sidebar
  icon: rocket # an icon from Blume's built-in set
  badge: New # a small label beside the entry
  order: 1 # sort position within its group

ページスキーマの全体についてはフロントマターを参照してください。

フォルダーグループ

各フォルダーはサイドバーのグループになります。ページと並べて meta.ts を置くと、グループのタイトル、アイコン、順序、および子要素の順序を設定できます。

import { defineMeta } from "blume";

export default defineMeta({
  title: "Guides",
  icon: "book-open",
  pages: ["configuration", "theming", "deployment"],
});

すべてのフィールドとスキャン時の meta の計算についてはフォルダー meta を参照してください。

フォルダーの meta.title と、そのフォルダー自身の index ページのフロントマター title は独立して解決されます — i18n で片方だけを翻訳してもう一方を忘れると、サイドバーは正しく表示される一方で、ランディングページ自体の <title> や見出しが古いままになります。両者が食い違うと、Blume は BLUME_NAV_INDEX_TITLE_MISMATCH 警告を報告します。フォールバックロケールから補完された未翻訳のページは対象外です — そのタイトルはフォールバックロケールのものであり、修正すべきはページの翻訳であって、フロントマターの編集ではありません。

URL セグメントを追加せずにページをグループ化するには、括弧付きのフォルダー名を使います — ページを参照してください。

表示モード

navigation.sidebar.display は、すべてのサイドバーグループの描画方法を設定します。

navigation: {
  sidebar: {
    display: "flat", // "flat" | "group" | "page"
  },
}
  • flat（デフォルト）— 折りたためないヘッダーの下にページを並べます。どのグループにも属さないページは常に先頭、グループのセクションより上に並ぶため、グループの子要素と取り違えられることがありません。
  • group — グループごとに折りたたみ可能な <details> 開閉要素になります。グループはデフォルトで折りたたまれた状態から始まりますが、現在のページを含むグループは常に開いた状態で始まるため、今いるセクションだけが展開されます。フォルダー meta で collapsed: false を設定すると、状況にかかわらずグループを開いた状態に固定できます。
  • page — 各グループが 1 行になり、クリックするとサイドバーがそのグループの項目だけを表示するサブパネルにスライドし、上部に戻る矢印が表示されます。パネルはルートを認識するため、グループ内のページに直接アクセスした場合はそのページが表示された状態で開きます。

グループ単位の上書き

生成されたグループは、明示的なサイドバーを用意しなくてもグローバルなモードから外れることができます。フォルダーの meta.ts で display を設定するか、そのフォルダーに index ページがある場合はそのページのフロントマターの sidebar 以下で設定すると、そのグループだけが変わります。

import { defineMeta } from "blume";

export default defineMeta({
  title: "Client SDKs",
  display: "page",
});
---
title: Client SDKs
sidebar:
  display: page
---

生成されたグループの実効モードは、優先度の高いものから順に解決されます。

  1. グループ自身の index ページのフロントマターの sidebar.display
  2. フォルダーの meta.ts の display
  3. グローバルな navigation.sidebar.display
  4. Blume のデフォルト（flat）

グループの display はそのグループにのみ適用されます — 入れ子のサブグループは、同じ連鎖を通じて自身の値を解決します。インデックスページを持つ page モードのグループも、これまでどおりサブパネルへ掘り下げます。インデックスページはパネルの最初の項目として並び、その URL にアクセスするとパネルが直接開きます。

sidebar.display は、それ以外の場所では意味を持ちません — インデックス以外のページ、コンテンツルート自身の index ページ（ルートはグループではありません。navigation.sidebar.display を使ってください）、および明示的なサイドバーが設定されている場合のあらゆるページ（その項目が各グループのモードを決めます）です。そのため Blume は、黙って無視する代わりに BLUME_SIDEBAR_DISPLAY_IGNORED 警告を報告します。collapsed は引き続き group モード専用で、グループが flat や page に解決される場合は効果がありません。

明示的なサイドバー内のグループは、これまでどおり自身の display でグローバルなモードを上書きできます。

並び順

サイドバーが生成されるとき、順序は優先度の高いものから順に解決されます。

設定のサイドバー

明示的な navigation.sidebar は、生成されたツリーを完全に置き換えます。

フォルダー meta

meta.ts の pages 配列がグループの順序を決めます。

フロントマター

ページの sidebar.order。

ファイルシステム

index ページが最初、次に数値プレフィックス、その後ラベルのアルファベット順。

明示的な順序または数値の順序が同じになった 2 つの兄弟要素は、その 2 つの間ではアルファベット順にフォールバックします — Blume は BLUME_DUPLICATE_SIDEBAR_ORDER 警告を報告するので、この重複が見過ごされることはありません。

非表示のページ

ページをビルドしたまま URL からアクセス可能に保ちつつ、サイドバーと前後のページネーションから隠します。

sidebar:
  hidden: true

タブ

トップレベルのセクションをヘッダーのタブとして描画します。大規模なサイトを別々の領域に分割する場合 — たとえばアダプター、API、AI ガイドなど — に便利です。現在のルートがタブの path の配下にある場合、そのタブがハイライトされます。

navigation: {
  tabs: [
    { label: "Adapters", path: "/adapters", icon: "plug" },
    { label: "API", path: "/api", icon: "rocket" },
    { label: "AI", path: "/ai", icon: "sparkles" },
  ],
}

有効化された OpenAPI または AsyncAPI リファレンスは自身のルートにマウントされますが、それ自体でタブが追加されるわけではありません — そのルートを指すタブを設定すると、好きなラベルでヘッダーに表示できます（ネイティブレンダラーの場合は、操作用サイドバーのスコープも設定されます）。

navigation: {
  tabs: [
    { label: "API", path: "/reference" },
  ],
}

タブの path はそのセクションのプレフィックスであり、リンク先も兼ねます。path が自身のページを持たないセクション — index.mdx のないフォルダー — は 404 にリンクしてしまうため、タブは代わりにそのセクションの最初のページにフォールバックします。別の場所に遷移させたい場合は href を設定してください。

navigation: {
  tabs: [
    { label: "Changelog", path: "/changelog", href: "/changelog" },
  ],
}

これはコンテンツツリーに含まれないルートで重要になります。フォールバックはそれらを認識できないためです。たとえば生成されたチェンジログのインデックスや、pages/ 以下に追加したカスタムページなどです。href がないと、/changelog タブはインデックスではなく最新のエントリーに遷移します。href を設定していないタブは影響を受けません。

i18n サイトでは、タブの label（およびドロップダウン項目のラベル）を文字列ではなくロケールごとのマップにできます — アクティブなロケールのエントリーが優先され、次にデフォルトロケールのものが使われます。

navigation: {
  tabs: [
    { label: { en: "Docs", fr: "Documentation" }, path: "/docs" },
    { label: "CLI", path: "/cli" }, // a plain string renders as-is everywhere
  ],
}

タブはサイドバーのスコープも設定します。現在のルートがタブの path の配下にある場合、サイドバーにはそのセクションのページだけが表示されます — つまり /adapters/* ではアダプターだけが並び、それ以外は表示されません。タブの path にあるフォルダーがそのセクションになるため、タブ自体以外の追加設定は不要です。コンテンツをタブごとのフォルダーに構造化し、各タブをそれに向けてください。

どのタブにも属さないルート（または path が / のタブ）では、サイドバーにはタブに属さないページが表示されます — 各タブのフォルダーはそこから隠されます。そのセクションはすでにヘッダーに自身のタブを持っているからです。したがってルートのランディングページでは、セクション化されたコンテンツがタブの向こうに留まったまま、独立したトップレベルのページが並び、Fumadocs のルートフォルダーと同じ挙動になります。この方法で表示できるページがルートに 1 つもない場合は、代わりにツリー全体が表示されるため、サイドバーが空白になることはありません。

セレクター

サイト全体のパーティション — 製品、バージョン、あるいはグループ化された任意の遷移先の集合 — を切り替えるには、selector を追加します。それぞれヘッダーにドロップダウンとして描画され、現在のルートに path が一致する選択肢が表示されます。

navigation: {
  selectors: [
    {
      kind: "version",
      label: "Version",
      items: [
        { label: "v2 (latest)", path: "/v2", icon: "rocket" },
        { label: "v1", path: "/v1" },
      ],
    },
  ],
}

各項目は label、path、および任意の icon、description、tag を取ります。kind（dropdown、product、version、language）はセレクターの用途を示すヒントで、いずれも同じドロップダウンとして描画されます。

バージョニングを設定している場合、Blume はバージョンセレクターを自動的に描画します — ここで独自の kind: "version" セレクターを宣言すると自動のものが置き換えられるため、手作りの構成もこれまでどおり動作します。

注目リンク

リンクをサイドバーの最上部、すべてのセクションより上に固定します — ブログ、チェンジログ、常に 1 クリックで届くべき問い合わせやサポートのページなどです。生成されるツリーと異なり、注目リンクはタブによるスコープの対象外です。あらゆるルート、あらゆるブレークポイントで表示されます。

navigation: {
  featured: [
    { label: "Blog", href: "https://example.com/blog", icon: "newspaper" },
    { label: "Contact", href: "/contact", icon: "headphones" },
  ],
}

各リンクは label、href、および任意の icon（組み込みアイコン名、画像のパスや URL、インライン SVG — 他の箇所と同じです）を取ります。href はどこを指してもかまいません。外部 URL は新しいタブで開き、内部ルート（/contact）はビルド時にページと照合され、一致するものがなければ警告されます。

明示的なサイドバー

完全に制御したい場合は、navigation.sidebar に明示的な項目を列挙します — 素の配列は sidebar.items の省略記法であり、オブジェクト形式ではそれらをグローバルな display と組み合わせられます。項目が設定されると、Blume はそれをそのまま使用し、ファイルシステムからの生成をスキップします。

navigation: {
  sidebar: [
    "/", // a page, referenced by route
    {
      label: "Guides", // a group
      collapsed: false,
      items: ["/configuration", "/configuration/theming"],
    },
    { label: "GitHub", href: "https://github.com/owner/repo" }, // an external link
  ],
}

各項目は、ページのルート（文字列）、グループ（label + items）、またはリンク（label + href）です。グループは入れ子にでき、グローバルな display モードを上書きでき、collapsed の状態から始めることもできます。

ヘッダーアクション

navigation.actions はヘッダーのアイコンボタンの左側に素のリンクを配置し、navigation.cta は唯一の塗りつぶしボタンです。

navigation: {
  actions: [{ href: "/changelog", label: "Changelog" }],
  cta: { href: "https://example.com/signup", label: "Start free" },
}

cta が単数なのは意図的です — ドキュメントのヘッダーには、読者に求める行動をちょうど 1 つ置く余地しかなく、ボタンが並んでいては何も求めていないのと同じです。二次的なリンクは actions に、あるいはサイドバー側に置きたい場合は featured に含めてください。

http(s) またはプロトコル相対の href は新しいタブで開きます。ルートは同じタブに留まり、featured リンクと同様にビルド時にページと照合されます — そのため、同じホスト上の別アプリが配信するページ（たとえば製品側の /signup）は絶対 URL として書いてください。actions は sm ブレークポイント未満では非表示になります。そこではヘッダーにロゴとナビゲーションのトグルを置く余地しかないためです。cta もそこでは非表示になりますが、ナビゲーションのトグルがないページ — タブのない PageLayout のランディングページ — では、スマートフォンで他にそれを表示する手段がないため、そのまま残ります。

リポジトリリンク

設定で github を指定すると、Blume はヘッダーの — テーマ切り替えの隣に — リポジトリへリンクする GitHub アイコンを表示します。デフォルトで有効で、navigation.repo で非表示にできます。

navigation: {
  repo: false, // hide the header GitHub link (default: true)
}

このリンクは github が設定されている場合にのみ表示されるため、リポジトリのないプロジェクトはいずれにせよ影響を受けません。

repo は絶対 URL も受け取ることができ、ヘッダーのマークを GitHub 上の任意の場所へ向けられます。

navigation: {
  repo: "https://github.com/acme",
}

これはドキュメントのリポジトリが非公開のプロジェクト向けです。github はページごとの編集リンク、ヘッダーのマーク、エージェントマニフェストのリポジトリをまとめて制御するため、そうしたプロジェクトは github を未設定のままにするしかありません — そして URL があれば、公開されたどこかを指すマークを引き続き表示できます。アイコンは GitHub のマークのままなので、別のホストへのリンクは actions に置いてください。

パンくずリストとページネーション

これらはサイドバーツリーから自動的に得られ、設定は不要です。

  • パンくずリストは、タイトルの上に現在のページの親グループを表示します。
  • 各ページ末尾の前後のリンクはサイドバーの順序に従い、非表示のページはスキップします。

このページの内容

右レールのアウトラインは各ページの ## と ### 見出しから自動生成されるため、長いページでも見通しが保たれます。右レールが隠れる狭い画面では、コンテンツの上にある「このページの内容」ドロップダウンに折りたたまれます。

ページアクション

目次の下には、どのページにも一連のクイックアクションが表示されます。

  • GitHub で編集 — ソースファイルへ直接リンクします。設定で github を指定すると表示されます。
  • トップへスクロール — 長いページの先頭へなめらかに戻ります。
  • フィードバックを送る — 任意のリアクションとメモを添えて、内容が事前入力された GitHub イシューを開きます（こちらも github が必要です）。

そのほかに、ページを AI ツールに渡すアクション — Markdown としてコピーとチャットで開く — があり、AI で説明しています。

export を有効にすると、エクスポートアクションによって読者がページを PDF や EPUB としてダウンロードできるようにもなります。

このページは役に立ちましたか？