コンテンツにスキップ
Blume is now publicly available.
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 行になり、クリックするとサイドバーがそのグループの項目だけを表示するサブパネルにスライドし、上部に戻る矢印が表示されます。パネルはルートを認識するため、グループ内のページに直接アクセスした場合はそのページが表示された状態で開きます。

明示的なサイドバー内のグループは、自身の 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）はセレクターの用途を示すヒントで、いずれも同じドロップダウンとして描画されます。

注目リンク

リンクをサイドバーの最上部、すべてのセクションより上に固定します — ブログ、チェンジログ、常に 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 の状態から始めることもできます。

リポジトリリンク

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

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

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

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

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

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

このページの内容

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

ページアクション

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

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

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

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

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