MDX Runtime Helpers

Methanol automatically injects a lightweight runtime context into every MDX file, facilitating the creation of dynamic content and simplified template integration.

Context Variables

The following helpers are globally available within MDX pages:

• ctx: The complete page and site context object.
• frontmatter: An alias for ctx.page.frontmatter.
• rawHTML: A utility for injecting unescaped HTML content.

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

Current Route: {ctx.routePath}

Context Structure

Key properties available on the ctx object:

• ctx.page: Metadata for the current page (see detailed schema below).
• ctx.pages: Flat list of pages for navigation (excludes exclude: true and omits /404 + /offline unless hidden: false).
• ctx.pagesByRoute: Map of routePath -> page for fast lookup.
• ctx.pagesTree: The hierarchical navigation tree scoped to the current root.
• ctx.site: Site-wide metadata (e.g., name, root, pagesDir, distDir, pagefind).
• ctx.withBase(path): A utility that prefixes URLs starting with / with the configured site.base or Vite base (relative URLs remain unchanged).
• ctx.language: The currently active language entry (derived from directory index pages with lang; includes label and code).
• ctx.getSiblings(): Returns the { prev, next } page objects for the current page, respecting the active navigation root.
• ctx.routePath / ctx.routeHref: Route information for the current page.
• ctx.path: Absolute filesystem path for the current page.

Note: You typically do not need to use ctx.withBase() for theme.sources or static files in public/, as Methanol resolves these at build time. However, it is a useful safeguard for URLs generated dynamically via JavaScript in development environments.

ctx.site

ctx.site is a snapshot of site-level metadata and build flags, including:

• 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 Metadata Object

ctx.page provides comprehensive metadata for the current page. The full schema includes:

• routePath: The normalized route path (e.g., /guide/writing).
• routeHref: The base-aware href for linking (includes site.base / Vite base).
• path: The absolute filesystem path to the source file.
• source: Origin of the file ("user" or "theme").
• relativePath: The path relative to pagesDir (including extension).
• name: The filename without extension.
• dir: The directory path relative to pagesDir ('' for root).
• segments: An array of route segments.
• depth: The number of segments in the route.
• isIndex: Boolean, true if the file is an index.mdx.
• title: The resolved page title (from frontmatter or inferred from headings).
• frontmatter: The parsed YAML frontmatter object.
• matter: Raw frontmatter block metadata.
• content: Raw Markdown content excluding frontmatter.
• toc: Extracted Table of Contents entries.
• weight: Numeric sort order (from frontmatter).
• date: Normalized ISO date string (from frontmatter).
• isRoot: Boolean, true if the page defines a navigation root.
• hidden: Boolean, true if the page is hidden from navigation.
• hiddenByParent: String or null, the nearest hidden ancestor route (e.g., /hidden/).
• hiddenByParents: Boolean, true if the page is inside any hidden section.
• exclude: Boolean, true if the page is excluded from the build.
• stats.size: File size in bytes.
• stats.createdAt: File creation timestamp (ISO) if available.
• stats.updatedAt: Last modified timestamp (ISO) if available.

Note: Directory index routes always include a trailing slash in routePath (e.g., /guide/). ctx.page.getSiblings() is injected at runtime to facilitate previous/next navigation.

Usage Example:

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

ctx.pages List

ctx.pages is a flat array containing metadata objects (matching the ctx.page schema) for navigation. It excludes pages marked with exclude: true, and it omits /404 and /offline unless those pages are explicitly set to hidden: false. Hidden pages may still appear here, but ctx.pagesTree will filter them out.

This is ideal for generating custom indices, sitemaps, or manual navigation structures:

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

ctx.pagesTree Hierarchy

ctx.pagesTree represents the navigation hierarchy for the current root context (adhering to isRoot and hidden rules). Node structure:

• type: "page" or "directory"
• title / name: Display label.
• routePath / routeHref: Route for the node.
• children: Array of child nodes (for directories).

Use this to construct navigation UIs that mirror the sidebar structure:

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

ctx.getSiblings Helper

ctx.getSiblings() retrieves the preceding and succeeding pages in the current navigation sequence. It respects the active navigation root and visibility rules, ensuring consistency with the sidebar order.

{(() => {
  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 Utility

The rawHTML helper allows for the injection of unescaped HTML. This is particularly useful for inline scripts or specific markup that must remain unsanitized.

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

rawHTML supports reactivity via signals and standard template interpolation.