MDX ランタイムヘルパー

Methanol は、各 MDX ページに軽量なランタイムコンテキストを注入します。これにより、ページ情報の参照や動的なコンテンツ生成、テンプレートとの連携が容易になります。

コンテキスト値

MDX 内では、以下の変数が常に利用可能です。

• ctx: ページおよびサイト全体のコンテキスト
• frontmatter: ctx.page.frontmatter のエイリアス
• rawHTML: エスケープ処理を介さずに生の HTML を挿入するためのインターフェース

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

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

コンテキストのデータ構造

ctx オブジェクトの主要なフィールドは以下の通りです。

• ctx.page: 現在表示中のページのメタデータ（詳細は後述）
• ctx.pages: サイト内の全ページリスト（非表示ページやインデックスページを含む）
• ctx.pagesTree: 現在のナビゲーションルートに基づいた階層ツリー構造
• ctx.site: サイト全体の基本情報（name, root, pagesDir, distDir, pagefind など）
• ctx.withBase(path): ルート（/）から始まるパスに、site.base または Vite の Base Path を自動付与します（相対パスは変更されません）
• ctx.language: 現在有効な言語設定（ディレクトリの index.mdx に lang が設定されている場合。label と code を含みます）
• ctx.getSiblings(): 現在のページの前後（prev, next）のページ情報を取得します

注意: theme.sources で定義された URL や public/ ディレクトリ内の静的ファイルは、通常ビルド時に自動解決されるため、ctx.withBase() を明示的に使用する必要はありません。ただし、JavaScript で動的に URL を生成する場合など、開発環境でのパス解決に問題が生じる際の回避策として有効です。

ctx.page オブジェクト

ctx.page は、現在のページの情報を保持するメタデータオブジェクトです。

• routePath: 正規化されたルートパス（例: /guide/writing）
• routeHref: リンクに使用する、Base Path を考慮した Href（site.base を含みます）

補足: ディレクトリのインデックスページの場合、routePath の末尾には / が付与されます（例: /guide/）。

• filePath: ソースファイルの絶対パス
• title: 解決済みのページタイトル（フロントマターまたは見出しから抽出）
• frontmatter: 解析済みの YAML フロントマター
• toc: ページ内から抽出された目次データ
• isIndex: index.mdx ファイルの場合に true
• dir: pagesDir からの相対ディレクトリパス
• segments: ルートを分割したセグメント配列
• hidden: ナビゲーションメニューから非表示に設定されているか
• isRoot: ナビゲーションのルートノードとして設定されているか
• date: フロントマターで日付が指定されている場合の ISO 文字列
• updatedAt: ファイルの最終更新タイムスタンプ（取得可能な場合）

使用例:

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

ctx.pages リスト

ctx.pages は、サイト内の全ページのメタデータオブジェクトを格納した配列です。インデックスページや非表示ページも含まれますが、exclude: true が設定されたページは除外されます。

カスタムのページリスト、サイトマップ、または独自のナビゲーション UI の構築に適しています。

<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}>前へ: {siblings.prev.title}</a> : null}
      {siblings.next ? <a href={siblings.next.routeHref || siblings.next.routePath}>次へ: {siblings.next.title}</a> : null}
    </nav>
  )
})()}

rawHTML インターフェース

rawHTML を使用すると、エスケープ処理を回避して生の HTML を直接挿入できます。インラインスクリプトや、特定の HTML 構造をそのまま出力したい場合に便利です。

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

rawHTML はシグナル（Signals）やテンプレートリテラルによる補間にも対応しています。