ページ
content フォルダー内のファイルがどのようにページになるのか、そしてルーティングとナビゲーションが自動的に推論されるようにファイルを整理・命名する方法。
ドキュメントは Markdown ファイルと MDX ファイルが入ったフォルダーにすぎません。Blume は各ファイルをページに変換します。ルーティング、ナビゲーション、メタデータはファイルシステムから推論されるため、同期を保つべきマニフェストは存在しません。
コンテンツは コンテンツルート（デフォルトは docs/。blume.config.ts の content.root で変更できます）配下に置きます。
Markdown と MDX
Blume は 2 種類のファイルをレンダリングします。
.md— 純粋な文章向けの Markdown: GFM、フロントマター、スマート句読点、上付き・下付き文字。.mdx—.mdのすべての機能に加えて、コンポーネント と MDX 専用のディレクティブ、パッケージインストール、数式。
ページが文章だけの場合は .md を、コンポーネントやディレクティブが必要な場合は .mdx を使いましょう。切り替えはファイル名を変更するだけです。
.mdx では { が JavaScript 式の始まり、< が JSX タグの始まりになるため、.md では問題のないテキストでもページが壊れることがあります。たとえば、波括弧そのもの、HTML コメント（{/* … */} と書きます）、閉じられていない要素（<br /> と書きます）などです。Blume はプロジェクトを読み込む際にすべての .mdx ページをパースします。そのため、パースできないページがあると、blume dev、blume validate、blume doctor、blume check はそれを BLUME_MDX_SYNTAX として報告します。これは MDX のパースが止まった行と列を示すエラーです。また、blume build は何もコンパイルせずにその時点で停止します。--no-strict を指定すると、ビルドはそのページを除外し、サイトの残りの部分をビルドします。blume dev はそのページを保持し、開くとエラーが表示されます。
式はパースできても、ページのレンダリング時に失敗することがあります。たとえば、user がどこにも定義されていないページにある {user.name} などです。blume build はこれを BLUME_MDX_UNDEFINED_NAME として報告し、ページ内またはその式を含むパーシャル内の、式がある行を示します。波括弧をテキストとして表示するには、開き波括弧をそれぞれエスケープする（\{）か、テキストをインラインコードにしてください。すべてのページで共有する値には、変数を定義しましょう。
ファイルとルート
各ファイルは、コンテンツルート配下のパスに応じてルートに対応付けられます。
| ファイル | ルート |
|---|---|
docs/index.mdx |
/ |
docs/quickstart.mdx |
/quickstart |
docs/guides/theming.mdx |
/guides/theming |
docs/guides/index.mdx |
/guides |
ネストしたフォルダーはネストしたルートになり、フォルダー内の index.mdx はそのフォルダー自体のページになります。
ページの URL を壊してしまう文字（#、?、%、:）はルートから取り除かれるため、100%.mdx は /100 で公開されます。ただし、# と ? はファイル名やフォルダー名に一切使わないでください。Astro のコンテンツローダーはそのようなファイルを読み込めないため、Blume はエラーとして報告し、そのファイルをサイトから除外します。sdks/c#.mdx を sdks/c.mdx にリネームすると /sdks/c で公開されます。これは、いずれにせよ文字が取り除かれた場合と同じルートです。
数値プレフィックスによる並び替え
ファイルやフォルダーの先頭に数字と -、_、. のいずれかを付けると、サイドバーでの順序を制御できます。プレフィックスは URL から取り除かれるため、リンクを壊さずにページを並べ替えられます。
01-introduction.mdx -> /introduction
02-installation.mdx -> /installation名前の先頭にあるバージョンや日付は名前の一部として扱われ、並び順にはなりません。1.2.0.mdx は /1.2.0 に、2024-01-05-launch.mdx は /2024-01-05-launch にルーティングされます。Blume は次の形式を日付として読み取ります。
- ISO 日付（
YYYY-MM-DD）:2024-01-05.mdxは/2024-01-05にルーティングされます。 - 日または月が先頭にあり、その後に 4 桁の年が続く形式（
D-M-YYYYまたはM-D-YYYY。日と月は 1 桁または 2 桁）:12-05-2022.mdxは/12-05-2022にルーティングされます。 - 年と月（
YYYY-MM）:2024-01.mdxは/2024-01にルーティングされます。
日付は名前の末尾に来るか、名前のほかの部分と同じように、後ろに -、_、. のいずれかが続きます（2024-01-recap.mdx）。以前のバージョンの Blume は、後の 2 つの形式の最初の数字を並び順のプレフィックスとして読み取っていたため、12-05-2022.mdx は /05-2022 で、2024-01.mdx は /01 で公開されていました。現在、これらの古い URL は、そこに別のページが存在しない限り、新しい URL にリダイレクトされます。プレフィックスが取り除かれるのはファイル名とフォルダー名だけです（Obsidian vault のノートはファイルとして扱われます）。フロントマターの slug や、CMS や GitHub Releases などのコンテンツソースから取り込まれたページは、指定された名前をそのまま保持します。
並び順には複数の階層があります。優先順位の完全なルールはナビゲーションを参照してください。
グループフォルダー
フォルダー名を丸括弧で囲むと、URL セグメントを追加せずに、そのページ群をサイドバーでグループ化できます。
docs/(internal)/security.mdx -> /securityこれらのページはサイドバー上で「Internal」グループを共有しますが、URL は括弧のないフラットなままです。グループフォルダーにも、通常のフォルダーと同じように数値プレフィックスを付けられます。プレフィックスは括弧の内側と外側のどちらに置いても構いません。(01-internal) と 01-(internal) はどちらも先頭に並び、(internal) と同じようにルーティングされます。
下書き
ページを下書きとしてマークすると、本番ビルドからは除外しつつ、blume dev ではプレビューできます。
---
title: Work in progress
draft: true
---blume build は下書きをスキップし、blume dev はレンダリングするので、公開前の作業を進められます。
コンテンツタイプ
すべてのページには タイプ があり、フロントマターの type フィールドで設定します（デフォルトは doc）。タイプを使うと、Blume はページのグループごとに異なる扱いができます。中でも重要なのは、blog と changelog のページがフィードにまとめられる点です。
---
title: v1.2.0
type: changelog
date: 2026-06-20
changelog:
version: 1.2.0
category: Features
---タイプはファイルの置き場所とは独立していますが、慣例としてブログ記事は blog/ 配下に、changelog エントリーは changelog/ 配下に置きます。どちらも自動的に RSS フィードを取得し、changelog エントリーは生成された /changelog タイムラインにもまとめられます。それぞれの執筆方法についてはブログとChangelogを参照してください。
フィード
Blume は、seo.rss.types に列挙された各コンテンツタイプ（デフォルトは blog と changelog）について、ページが 1 つ以上あれば自動的に RSS フィードを生成します。フィードは /<type>/rss.xml で配信されます。
| タイプ | フィード |
|---|---|
blog |
/blog/rss.xml |
changelog |
/changelog/rss.xml |
各エントリーに date を指定すると、項目が新しい順に並び、pubDate が付与されます。クォートなしの YAML 日付でも問題ありません。Blume が正規化します。
---
title: Introducing Blume
type: blog
date: 2026-06-22
description: Why we built a markdown-first docs framework.
---フィードには絶対的なサイト URL が必要なので、deployment.site を設定してください。Blume はすべてのページに <link rel="alternate"> タグを追加するため、ブラウザーやフィードリーダーが自動的にフィードを検出します。各コンテンツタイプの執筆方法についてはブログとChangelogを参照してください。
このページの内容
すべてのページには、見出しから自動的に生成される目次が付きます。画面が広い場合はコンテンツの横の固定サイドバーに表示され、狭い場合はページ上部の このページの内容 パネルに折りたたまれます。スクロールすると、読んでいるセクションの項目がハイライトされるので、長いページでも現在位置が常に分かります。
Blume は各見出しをスラッグ化してアンカーにするため、すべての項目がそのセクションへ直接リンクします。また、URL にスラッグを付け加えることで任意の見出しへディープリンクできます（.../my-page#getting-started）。
デフォルトでは、目次には ## と ### の見出し（H2 と H3）が並びます。見出しの範囲を変更したり目次を無効にしたりするには、toc を設定してください。その範囲の見出しがないページには、単に目次が付きません。