MDX ランタイムヘルパー

Methanol は、すべての MDX ファイルに対して軽量なランタイムコンテキストを自動的に注入します。これにより、テンプレートや動的コンテンツの構築が容易になります。

コンテキスト変数

MDX ページ内では、以下のヘルパー変数が常に利用可能です。

• ctx: ページおよびサイト全体の完全なコンテキストオブジェクト。
• frontmatter: ctx.page.frontmatter のエイリアス。
• rawHTML: エスケープ処理を行わずに生の HTML を挿入するためのユーティリティ。

# {frontmatter.title ?? ctx.page.title}

現在のルート: {ctx.routePath}

コンテキストの構造

ctx オブジェクトで利用可能な主要プロパティは以下の通りです。

• ctx.page: 現在のページのメタデータ（詳細なスキーマは後述）。
• ctx.pages: サイト内の全ページ（非表示ページやインデックスページを含む）を網羅したフラットなリスト（exclude: true を除外し、hidden: false でない限り /404 と /offline を省略します）。
• ctx.pagesByRoute: 高速なルックアップのための routePath -> page の Map。
• ctx.pagesTree: 現在のルートにスコープされた階層的なナビゲーションツリー。
• ctx.site: サイト全体のメタデータ（name, root, pagesDir, distDir, pagefind 等）。
• ctx.withBase(path): / で始まる URL に対して、設定された site.base または Vite の base を付与するユーティリティ（相対 URL は変更されません）。
• ctx.language: 現在アクティブな言語エントリ（lang を持つディレクトリインデックスページから派生。label と code を含む）。
• ctx.getSiblings(): 現在のナビゲーションルートを考慮した上で、前後（prev, next）のページオブジェクトを返します。
• ctx.routePath / ctx.routeHref: 現在のページのルート情報。
• ctx.path: 現在のページのファイルシステム上の絶対パス。

注: theme.sources や public/ 内の静的ファイルについては、Methanol がビルド時に解決するため、通常 ctx.withBase() を使用する必要はありません。ただし、開発環境において JavaScript で動的に URL を生成する場合の安全策として有用です。

ctx.site

ctx.site は、サイトレベルのメタデータとビルドフラグのスナップショットであり、以下を含みます。

• name, owner, base, mode
• root, pagesDir, componentsDir, publicDir, distDir
• pagefind (enabled, options, build)
• feed (enabled, atom, path, href)
• pwa (enabled, manifestPath, manifestHref)
• generatedAt

ctx.page メタデータオブジェクト

ctx.page は、現在のページに関する包括的なメタデータを提供します。完全なフィールド一覧は以下の通りです。

• routePath: 正規化されたルートパス（例: /guide/writing）。
• routeHref: リンク用の Base Path 対応 Href（site.base / Vite base を含む）。
• path: ソースファイルの絶対ファイルシステムパス。
• source: ファイルの由来（"user" または "theme"）。
• relativePath: pagesDir からの相対パス（拡張子を含む）。
• name: 拡張子を除いたファイル名。
• dir: pagesDir からの相対ディレクトリパス（ルートの場合は ''）。
• segments: ルートセグメントの配列。
• depth: ルートのセグメント数（深さ）。
• isIndex: ファイルが index.mdx の場合に true。
• title: 解決されたページタイトル（フロントマターまたは見出しから推論）。
• frontmatter: 解析済みの YAML フロントマターオブジェクト。
• matter: 生のフロントマターブロックメタデータ。
• content: フロントマターを除いた生の Markdown コンテンツ。
• toc: 抽出された目次（Table of Contents）エントリ。
• weight: ソート用の数値ウェイト（フロントマター由来）。
• date: 正規化された ISO 日付文字列（フロントマター由来）。
• isRoot: ページがナビゲーションルートを定義している場合に true。
• hidden: ページがナビゲーションから隠されている場合に true。
• hiddenByParent: 最も近い非表示ルートのパス（例: /hidden/）。該当しない場合は null。
• hiddenByParents: 非表示ルートの配下にある場合に true。
• exclude: ページがビルドから除外されている場合に true。
• stats.size: ファイルサイズ（バイト単位）。
• stats.createdAt: ファイル作成日時（ISO、利用可能な場合）。
• stats.updatedAt: 最終更新日時（ISO、利用可能な場合）。

注: ディレクトリのインデックスルートには、常に末尾にスラッシュが含まれます（例: /guide/）。 ctx.page.getSiblings() は、前後ナビゲーションを容易にするためにランタイムで注入されます。

使用例:

{ctx.page.title}
{ctx.page.frontmatter?.excerpt}

ctx.pages リスト

ctx.pages は、プロジェクトおよびテーマ内の全ページ（ctx.page スキーマに一致）を含むフラットな配列です。exclude: true が設定されたページは除外され、/404 および /offline ページは hidden: false が明示的に設定されていない限り除外されます。非表示ページ（hidden: true）はここに含まれる場合がありますが、ctx.pagesTree ではフィルタリングされます。

カスタムインデックス、サイトマップ、または手動ナビゲーション構造の生成に最適です。

<ul>
  {ctx.pages.map((page) => (
    <li><a href={page.routeHref || page.routePath}>{page.title}</a></li>
  ))}
</ul>

ctx.pagesTree 階層

ctx.pagesTree は、現在のルートコンテキストにおけるナビゲーション階層を表します（isRoot および hidden ルールに準拠）。ノード構造:

• type: "page" または "directory"
• title / name: 表示ラベル。
• routePath / routeHref: ノードのルート。
• children: 子ノードの配列（ディレクトリの場合）。

サイドバー構造を反映したナビゲーション UI の構築に使用します。

{ctx.pagesTree.map((node) => (
  <div>{node.title || node.name}</div>
))}

ctx.getSiblings ヘルパー

ctx.getSiblings() は、現在のナビゲーションシーケンスにおける前後のページを取得します。アクティブなナビゲーションルートと表示ルールを尊重し、サイドバーの順序との整合性を保ちます。

{(() => {
  const siblings = ctx.getSiblings()
  if (!siblings) return null
  return (
    <nav>
      {siblings.prev ? <a href={siblings.prev.routeHref || siblings.prev.routePath}>Previous: {siblings.prev.title}</a> : null}
      {siblings.next ? <a href={siblings.next.routeHref || siblings.next.routePath}>Next: {siblings.next.title}</a> : null}
    </nav>
  )
})()}

rawHTML ユーティリティ

rawHTML ヘルパーを使用すると、エスケープされていない HTML を注入できます。これは、インラインスクリプトや、サニタイズされるべきでない特定のマークアップに特に有用です。

{rawHTML('<span class="badge">Beta</span>')}
{rawHTML`<div data-banner="true">Banner</div>`}

rawHTML は、シグナルによるリアクティビティや標準的なテンプレート補間に対応しています。