Methanol Docs

Using Components

2026-08-08T07:54:27.449Z

Using Components

MDX allows you to directly embed rEFui JSX components within your Markdown. By placing reusable components in the components/ directory, they become seamlessly integrated and available for use across all pages.

Component Creation

// components/Callout.jsx
export default function Callout(props, ...children) {
	return <div class="callout">{...children}</div>
}

Utilization in MDX

<Callout>
  Tip: Maintain concise and focused sections to improve readability.
</Callout>

Client-side Interactivity

For components that require access to browser-specific APIs, append the .client suffix to the filename:

components/Map.client.jsx

Interactive Example: Counter

Below is a simple interactive component:

// components/Counter.client.jsx
import './Counter.css'
import { signal } from 'refui'

export default function Counter({ initial = 0 }) {
	const count = signal(initial)
	return (
		<div class="counter">
			<button on:click={() => count.value--}>-</button>
			<span>{count}</span>
			<button on:click={() => count.value++}>+</button>
		</div>
	)
}

As this component includes a CSS import (which is incompatible with server-side static rendering), a corresponding static version must be provided for the build process:

// components/Counter.static.jsx
export default function Counter({ initial = 0 }) {
	return (
		<div>
			[ JavaScript is required to load this component. ]
		</div>
	)
}

Invoking the component within a page:

<Counter initial={5}/>

Live Preview:

[ You need to enable JavaScript to load this component. ]

For more advanced component patterns, refer to Custom Components.

Configuration

2026-08-08T07:50:39.769Z

Configuration

Methanol automatically resolves configuration from the following file patterns:

methanol.config.{js,mjs,cjs,ts,jsx,tsx,mts,cts}

In the absence of a configuration file, Methanol applies sensible defaults inferred from the project's root directory.

Configuration Schema

The configuration file must export a function that receives an execution context and returns a configuration object.

export default ({ mode, root, HTMLRenderer }) => ({
	// configuration properties
})

Execution context properties:

mode: Either development or production.
root: The absolute path to the project root.
HTMLRenderer: rEFui HTML utilities (including rawHTML and serialize).

Core Options

`root`

The project root directory. Defaults to the current working directory (CWD).

`site`

Site-wide metadata utilized by templates:

site.name: The title of the site.
site.owner: The site owner or author (used in the blog theme footer and feeds).
site.logo: Path to the logo asset (string), or false to disable (standard theme support).
site.favicon: Path to the favicon asset (string), or false to disable (standard theme support).
site.base: The Base Path prefix used when the site is hosted under a subpath (e.g., '/docs/').
site.repoBase: The base URL for the content directory within a repository, used by the standard theme to generate "Edit this page" links.

Notes:

site.base is automatically normalized to include both leading and trailing slashes (e.g., docs becomes '/docs/').
site.base configures the Rsbuild asset prefix and server base used by build, dev, and preview.
methanol dev preserves site.base, so subpath deployments can be tested directly in development.

`pagefind`

Enables and configures full-text search via Pagefind. Default: false.

pagefind: false
// or
pagefind: { enabled: true }
// or detailed configuration
pagefind: {
	enabled: true,
	excerptLength: 30,
	build: {
		outputSubdir: 'pagefind',
		verbose: true
	}
}

Notes:

Properties other than enabled and build are passed directly to the Pagefind JavaScript options() initialization.
The build object contains options specific to the build-time indexing process.

`feed`

Enables RSS/Atom feed generation. Default: false.

feed: true
// or
feed: {
	enabled: true,
	path: '/rss.xml',
	limit: 10,
	siteUrl: 'https://example.com',
	title: 'My Site',
	description: 'Updates from my site',
	language: 'en',
	atom: false
}

Notes:

Use atom: true to output Atom instead of RSS (default paths: /rss.xml or /atom.xml).
siteUrl must be an absolute URL. If omitted, Methanol uses site.base, so set it to a full origin (e.g. https://example.com/).
Hidden pages are excluded. limit defaults to 10.
Feed items use frontmatter.author when provided, falling back to site.owner.

`pwa`

Enables Methanol's built-in PWA support, featuring a custom service worker and an automated precache manifest. Default: false.

pwa: true
// or
pwa: false
// or detailed configuration
pwa: {
	manifest: {
		name: 'My Site',
		short_name: 'My Site'
	},
	precache: {
		include: ['**/*.{html,js,css,ico,png,svg,webp,jpg,jpeg,gif,woff,woff2,ttf}'],
		exclude: ['**/*.map', '**/pagefind/**'],
		priority: null,
		limit: null,
		batchSize: null
	}
}

Notes:

manifest is merged into the generated manifest.webmanifest.
precache configuration governs precache-manifest.json, used by the built-in service worker for installation and warming.
precache.priority: Ordered list of glob patterns to cache immediately.
precache.limit: Maximum number of entries in the precache manifest (null for unlimited).
precache.batchSize: Number of concurrent fetches during installation/warmup.
The precache manifest is generated from the finalized dist/ tree rather than the Rsbuild module graph. It excludes sw.js and precache-manifest.json to avoid self-referential revisions.
To fully customize PWA behavior, set pwa: false and provide your own manifest and service worker.

`starryNight`

Controls syntax highlighting via Starry Night (rehype-starry-night). Default: true.

starryNight: false
// or
starryNight: true
// or detailed configuration
starryNight: {
	// options passed to rehype-starry-night
}

When configured as an object, highlighting is enabled unless enabled: false is explicitly set.
Per-page Frontmatter settings always take precedence over global configuration.
The CLI flags --highlight and --no-highlight can be used to override this setting per-execution.
Methanol automatically loads grammars for fenced code languages it encounters. Use starryNight.grammars only to force ambiguous mappings or to supply unsupported grammars.

`jobs`

Controls the worker thread count used during the build pipeline. Default: 0 (auto based on page count).

jobs: 0 // auto (round(ln(pageCount))), clamped to CPU cores
// or
jobs: 4

The CLI flag --jobs (alias -j) overrides this setting per-execution.

`gfm`

Enables or disables GitHub Flavored Markdown (GFM) support. Default: true.

When enabled, Methanol applies GFM-specific parsing, including tables, task lists, strikethrough, footnotes, and autolink literals.

gfm: true
// or
gfm: false

`pagesDir`

The source directory for MDX and Markdown files. Defaults to pages, with an automatic fallback to docs if pages/ is not found.

`componentsDir`

The directory for JSX/TSX components. Defaults to components.

If pagesDir or componentsDir are explicitly defined (via configuration or CLI) but do not exist, Methanol will throw an error.

`publicDir`

The directory for static assets served at the site root (e.g., public/foo.png maps to /foo.png). Default: public.

Methanol automatically merges assets from the theme's publicDir. In the event of a path conflict, user-provided assets override theme assets.

Temporary merged assets are managed within node_modules/.methanol/assets (or {pagesDir}/.methanol/assets if node_modules/ is unavailable).

Set publicDir: false to disable all static asset processing.

`distDir`

The destination directory for production builds. Default: dist.

`buildDir`

The directory for intermediate build artifacts. Default: build.

`intermediateDir`

Explicit directory for intermediate HTML output (build only).

`emitIntermediate`

Boolean. If true, Methanol writes intermediate HTML to the build/ directory during the build process.

`theme`

Configures the site's theme. This can be a theme object (see below) or a string. When a string is provided, Methanol resolves it using the following priority:

Built-in Themes: Matches against Methanol's internal themes (e.g., default, blog).
Package Resolution: Searches for a package named methanol-theme-xxx (where xxx is your input).

For local themes (files inside your project), import them in methanol.config.* and set theme to the imported theme object/factory.

Refer to the Advanced Theme Guide for complete specifications of the theme object.

theme.root: The theme's root directory (required).
theme.template: The JSX function defining the HTML layout.
theme.components: Default components provided by the theme.
theme.componentsDir: Directory for theme-specific components.
theme.pagesDir: Directory for theme-provided pages.
theme.publicDir: Theme static assets (merged into publicDir).
theme.sources: Virtual path mappings resolved by Methanol.
theme.mdx: Default MDX options merged with user settings.
theme.rsbuild: Default Rsbuild configuration merged with user settings.

`mdx`

Customizes the MDX compilation process. Receives { mode, root } and returns an MDX options object.

With the built-in MDX pipeline, compiled page output is cached under {pagesDir}/.methanol/cache/mdx. This generated directory is safe to delete and should not be committed. Source, Frontmatter, compiler, and relevant local-link changes invalidate the affected page entry. Production builds still execute every page module, synchronize derived titles and ToCs, and re-render every page, so shared navigation always reflects metadata changes. Persistent reuse is disabled when user or theme mdx configuration is present because arbitrary plugin behavior cannot be safely fingerprinted.

`rsbuild`

Deep-merges custom Rsbuild configuration. A configuration function receives { command, mode, root, isPreview }, where command is build, dev, or preview.

Methanol owns the project root, generated entries, output root, asset manifest, public directory integration, and HTML processing. Other Rsbuild settings—including plugins, resolution, source transforms, server options, and output optimization—can be extended normally.

Build Hooks

Hooks for extending the build pipeline.

preBuild: Executes at dev server initialization and prior to the build process.
preBundle: Build only; executes after page rendering but before Rsbuild asset bundling.
postBundle: Build only; executes after Rsbuild bundling and before HTML asset rewriting.
preWrite: Build only; executes immediately before generated HTML is rewritten and written.
postWrite: Build only; executes after generated HTML is written.
finalize: Build only; executes after output is written but before Pagefind, feeds, and PWA manifests are generated.
postBuild: Build only; executes after the entire build process is complete.
Hooks accept either a single function or an array of functions.
Execution sequence: preBuild → Render → preBundle → Rsbuild bundle → postBundle → preWrite → HTML rewrite → postWrite → finalize → Pagefind/feed/PWA generation → postBuild. User and theme hooks run in Methanol's documented phase order.

Hook Context:

mode, root, command, isDev, isBuild, isPreview.
HTMLRenderer.
site (reflects the current ctx.site state).
data: A mutable object for sharing state across the hook lifecycle.

Build-only hooks additionally receive:

pagesContext, pages, pagesTree, and pagesByRoute.

Example:

export default () => ({
	preBuild: ({ data, site }) => {
		data.startedAt = Date.now()
		console.log('Building:', site.name)
	},
	preBundle: ({ pages }) => {
		console.log('Total rendered pages:', pages.length)
	},
	postBuild: ({ data, pages }) => {
		console.log('Build duration (ms):', Date.now() - data.startedAt)
		console.log('Final page count:', pages.length)
	}
})

CLI Overrides

Command-line arguments take precedence over configuration file settings:

--input and --components override pagesDir and componentsDir.
--assets overrides publicDir.
--output overrides distDir.
--site-name overrides site.name.
--owner overrides site.owner.
--base temporarily overrides site.base.
--search/--no-search override pagefind.enabled.
--rss/--no-rss override feed.enabled.
--atom/--no-atom override feed.atom.
--pwa/--no-pwa override the pwa toggle.
-v/--verbose enables detailed build logging.
--config specifies a non-standard configuration file.
Positional input/output arguments map to the --input/--output flags.

Implementation Example

import { pluginTailwindcss } from '@rsbuild/plugin-tailwindcss'

export default ({ mode }) => ({
	site: { name: 'Technical Docs' },
	theme: {
		root: '.',
		template: ({ PageContent, ExtraHead, ctx, withBase, HTMLRenderer, components }) => (
			<>
				{HTMLRenderer.rawHTML`<!doctype html>`}
				<html lang="en">
					<head>
						<meta charset="UTF-8" />
						<meta name="viewport" content="width=device-width" />
						<ExtraHead />
						<title>{ctx.page.title || ctx.site.name}</title>
						<link rel="icon" href="/favicon.png" />
					</head>
					<body>
						{components.Callout ? <components.Callout>Important Note</components.Callout> : null}
						<PageContent />
					</body>
				</html>
			</>
		),
		components: {
			Callout: ({ children }) => <div class="callout-component">{children}</div>
		}
	},
	mdx: () => ({
		development: mode !== 'production'
	}),
	rsbuild: () => ({
		server: { port: 3000 },
		plugins: [pluginTailwindcss()]
	})
})

Quick Start

2026-08-08T06:21:03.396Z

Quick Start

Methanol transforms a directory of Markdown and MDX files into a high-performance static site with automatic routing, navigation, and a robust build pipeline.

Getting started is simple: create pages/index.mdx, add your content, and Methanol will automatically build the routes and navigation tree.

Instant Preview

Experience Methanol immediately by running the development server via npx:

npx methanol dev

Then, open http://localhost:3000 in your browser.

Using an Existing Directory

If you already have a collection of Markdown or MDX files, point Methanol directly to that directory:

npx methanol dev ./my-docs

The specified folder becomes the content root; for example, ./my-docs/index.mdx maps to the site root (/).

Installation

For frequent use, we recommend installing Methanol globally to benefit from faster CLI startup:

npm install methanol -g
methanol dev

Production Workflow

Generate an optimized production build and preview it locally:

methanol build
methanol serve

The serve command hosts the contents of the dist/ directory for final verification.

Advanced Build Example

Methanol's CLI supports various flags to override configurations on the fly:

methanol build --pwa --search --theme blog --site-name "My Site"

This command enables PWA and search indexing, switches to the blog theme, and sets a custom site name.

Project Structure

pages/: MDX/MD source files (alternatively docs/).
components/: Reusable JSX/TSX components.
public/: Static assets (overrides theme-provided assets).
dist/: Optimized production output.

Files in public/ are served at the site root (e.g., public/logo.png → /logo.png).

Creating Your First Page

Create pages/index.mdx with the following content:

---
title: Home
---

# Welcome

This is my new documentation site.

The file structure is automatically mapped to URL routes:

pages/index.mdx       -> /
pages/guide.mdx       -> /guide
pages/blog/post.mdx   -> /blog/post

CLI

2026-08-08T06:20:51.188Z

CLI

Methanol includes a dedicated Command-line Interface (CLI) designed to streamline development, execution of static builds, and local previews.

Core Commands

Quick start with npx (recommended):

npx methanol dev      # Initialize the development server
npx methanol build    # Execute production build to the dist/ directory
npx methanol serve    # Preview the production build locally

For improved performance and faster startup times, consider a global installation:

npm install methanol -g
methanol dev

The input and output paths can be provided as positional arguments (order is significant):

npx methanol build ./pages ./dist

In dev mode, only the input argument is utilized:

npx methanol dev ./pages

For serve/preview, the first positional argument is treated as the output directory:

npx methanol serve ./dist

Flag Reference

--input, -i: Specifies the source directory (overrides the default pages/).
--components: Specifies the components directory (overrides the default components/).
--assets: Specifies the static assets directory (overrides the default public/).
--output, -o: Specifies the build destination (overrides the default dist/).
--config, -c: Defines the path to a custom configuration file.
--theme: Overrides the theme configuration. When a string is provided, Methanol first attempts to resolve it as a built-in theme (e.g., default, blog). If not found, it searches for a package named methanol-theme-xxx (where xxx is the provided string). For local themes, import them in methanol.config.* and set theme to the imported theme object/factory.
--site-name: Overrides the site title defined in configuration.
--owner: Overrides the site owner (site.owner).
--base: Temporarily overrides site.base for the current execution.
--port: Sets the port for the development and preview servers (default: 3000).
--host: Binds the server to a specific host (using --host without a value binds to all interfaces).
--intermediate-dir: Directory for intermediate HTML output (build only).
--emit-intermediate: Enables the output of intermediate HTML to build/ (build only).
--highlight/--no-highlight: Controls syntax highlighting.
--jobs, -j: Sets the build worker thread count (0 auto scales with page count).
--search/--no-search: Controls Pagefind search indexing.
--rss/--no-rss: Controls RSS/Atom feed generation.
--atom/--no-atom: Outputs Atom when enabled (--rss is implied).
--pwa/--no-pwa: Controls PWA support.
-v, --verbose: Enables detailed logging, including Rsbuild and Pagefind output during the build process.

Syntax highlighting is enabled by default and can be disabled per-execution via --no-highlight.

Execution via Node

node node_modules/methanol/bin/methanol.js dev

Offline Access (PWA)

2026-08-08T06:20:28.297Z

Offline Access (PWA)

Methanol includes a built-in PWA implementation featuring a custom service worker and an automated precache manifest. Critical assets are cached upon installation, while remaining content is warmed in the background with revision-aware updates.

Enabling PWA

Enable PWA support in methanol.config.js:

export default () => ({
	pwa: true
})

Manifest Customization

Customize the PWA manifest and precaching strategy as follows:

export default () => ({
	pwa: {
		manifest: {
			name: 'My Site',
			short_name: 'My Site'
		},
		precache: {
			include: ['**/*.{html,js,css,ico,png,svg,webp,jpg,jpeg,gif,woff,woff2,ttf}'],
			exclude: ['**/*.map', '**/pagefind/**']
		}
	}
})

Precache configuration:

priority: Glob patterns to cache immediately (moved to the top of the manifest).
limit: Maximum number of entries in the precache manifest.
batchSize: Number of concurrent fetches during installation/warmup.

Methanol creates the precache manifest from the finalized dist/ directory, independently of Rsbuild's module graph. The generated sw.js is standalone, and both sw.js and precache-manifest.json are excluded from their own revision list.

Advanced Configuration

For full control over the PWA lifecycle (e.g., custom service worker strategies), set pwa: false and supply your own manifest and service worker.

Custom Offline Page

Create pages/offline.mdx to define the fallback page displayed when a user is offline and the requested content is uncached. You may also define pages/404.mdx for "Not Found" errors; both are excluded from navigation by default.

Special-Purpose Pages

2026-08-08T06:18:31.504Z

Special-Purpose Pages

Themes can include pre-defined pages via theme.pagesDir. These pages follow standard routing rules, but user-provided pages always take precedence in the event of a route conflict.

This feature is ideal for providing:

Landing pages
Specialized index or menu screens
Link directories or contact forms
Theme-specific /404 or /offline fallbacks

Theme-Provided Pages

Define your pages directory in the theme entry point:

export default () => ({
	theme: {
		root: '.',
		pagesDir: './pages'
	}
})

Differentiated Layouts

The most effective way to implement specialized layouts is by defining a layout property in the page frontmatter.

Example menu.mdx:

---
title: Menu
layout: menu
hidden: true
---

# Menu content

Template implementation:

const MenuLayout = ({ ctx, PageContent }) => (
	<div class="menu-layout">
		<h1>{ctx.page.title}</h1>
		<PageContent />
	</div>
)

const DocLayout = ({ ctx, PageContent }) => (
	<div class="doc-layout">
		<aside>{/* Sidebar */}</aside>
		<main>
			<PageContent />
		</main>
	</div>
)

export default function PageTemplate({ PageContent, ExtraHead, ctx }) {
	const layout = ctx.page.frontmatter?.layout
	return (
		<>
			<html>
				<head>
					<ExtraHead />
					<title>{ctx.page.title || ctx.site.name}</title>
				</head>
				<body>
					{layout === 'menu' ? (
						<MenuLayout ctx={ctx} PageContent={PageContent} />
					) : (
						<DocLayout ctx={ctx} PageContent={PageContent} />
					)}
				</body>
			</html>
		</>
	)
}

Interactive Components

For pages requiring complex interactivity (e.g., contact forms), we recommend using client-only components. Your theme can provide these in its components/ directory (e.g., ContactForm.client.jsx), which users can then drop into their MDX pages.

Standalone HTML Pages

Special-purpose pages are not limited to MDX. You can include pure .html files in your theme's pagesDir. Their local scripts, styles, and assets are processed by Rsbuild before output.

This approach is excellent for standalone landing pages or embedded tools that should omit standard documentation elements like sidebars or ToCs. You can use ctx.page.path.endsWith('.html') within your template to apply a "standalone" layout.

Path and Asset Resolution

Methanol automatically resolves asset paths during the build process. While withBase() is generally not required for theme-provided static assets in public/, it remains a reliable tool for generating dynamic URLs that must remain base-path aware across different environments.

Themes

2026-08-08T06:18:31.503Z

Themes

Themes control layout (HTML template), default MDX components, and optional theme pages/assets. The default theme in the Methanol repo is a good reference.

Theme Implementation Guide

Theme Shape

export default () => ({
	theme: {
		root: './theme',
		componentsDir: './components',
		pagesDir: './pages',
		publicDir: './public',
		sources: {
			'/theme': './sources'
		},
		template: ({ PageContent, ExtraHead, ctx, page, withBase, HTMLRenderer, components }) => (
			<>
				{HTMLRenderer.rawHTML`<!doctype html>`}
				<html lang="en">
					<head>
						<meta charset="UTF-8" />
						<meta name="viewport" content="width=device-width" />
						<ExtraHead />
						<title>{page.title || ctx.site.name}</title>
						<link rel="icon" href="/favicon.png" />
					</head>
					<body>
						{components.Callout ? <components.Callout>Hi</components.Callout> : null}
						<PageContent />
					</body>
				</html>
			</>
		),
		components: {
			Callout: ({ children }) => <div class="callout">{children}</div>
		}
	}
})

Required

theme.root is required and defines the base directory for theme paths.

Defaults and Validation

componentsDir, pagesDir, publicDir can be:
- omitted (defaults to ./components, ./pages, ./public under the theme root; missing dirs are skipped)
- set to false (disables that feature for the theme)
- set explicitly (must exist or Methanol throws)

Theme Layout Files

Suggested structure:

theme/
  index.js          # exports the theme object
  page.jsx          # template component
  components/       # default MDX components
  pages/            # optional theme pages
  public/           # optional public assets
  sources/          # assets mapped by theme.sources

Theme public/ is merged into the project publicDir during dev/build. If a path exists in both, the project asset wins.

Template Contract

theme.template receives:

PageContent: JSX component for the current page content
ExtraHead: extra <head> content (page assets + Methanol runtime + per-page <Head>/head output)
ctx: page/site context (ctx.page, ctx.pages, ctx.pagesTree, ctx.pagesByRoute, ctx.languages, ctx.language, ctx.site, ctx.withBase, ctx.routePath, ctx.routeHref, ctx.path, ctx.getSiblings)
page: alias for ctx.page, providing page info
withBase: helper for base-aware URLs (same function as ctx.withBase)
HTMLRenderer: refui HTML renderer (for rawHTML/serialize, or for manually rendering JSX components)
components: merged components object (theme components + user components)

Return a JSX tree.

Important: put <ExtraHead /> inside <head>. Without it, per-page <Head>/head and automatic page assets won’t be injected.

When your site is deployed under a subpath (site.base !== '/'):

Use withBase('/...') (or ctx.withBase('/...')) for URLs that must follow the configured site/Rsbuild base, such as runtime assets.
Don’t apply withBase() to theme source URLs (theme.sources) or plain static files under public/; Methanol resolves those paths directly.

Theme Components

theme.components provides default MDX components. User components in the project components/ override theme components by name.

The template also receives components, which is the merged result (useful for layout-level components like nav/search).

Theme Pages

Theme pages follow the same routing rules as user pages. User routes always override theme routes.

A theme-provided /404 is used only when the user project does not define its own 404 page.

Theme Public Assets

If the theme provides a publicDir, Methanol copies its files into the user public directory at dev/build start. When the user sets publicDir, theme files are still copied into it; files with the same name are skipped. If the user does not have a public directory, Methanol falls back to the theme public directory.

Theme Sources

theme.sources maps virtual URLs to files. This is handled by Methanol’s resolver rather than Rsbuild aliases.

export default () => ({
	theme: {
		root: './theme',
		sources: {
			'/theme': './sources'
		}
	}
})

Theme Hooks

A theme can also provide build hooks (same shape as user config hooks):

preBuild (dev startup + before build)
preBundle (after pages are rendered, before Rsbuild bundles)
postBundle (after Rsbuild bundles, before HTML asset rewriting)
postBuild (after build)

Routing

2026-08-08T06:18:31.503Z

Routing

Methanol automatically constructs a routing hierarchy based on the structure of the pages/ directory.

MDX and Markdown Pages

pages/about.mdx → /about
pages/guide/index.mdx → /guide/ (directory index)

`.html` Pages

Plain HTML files can also be placed within the pages/ directory. These are included in the production build and their local scripts, styles, and assets are processed by Rsbuild:

pages/custom.html → dist/custom.html (accessible via /custom.html)

Example:

Custom HTML page

404 Page

Create pages/404.mdx to customize the "Not Found" page. This page is automatically hidden from the navigation menu.

Offline Page

Create pages/offline.mdx to customize the offline fallback page utilized by the built-in PWA. This page is also hidden from navigation by default.

Hidden vs. Excluded

hidden: true: Hides the page from navigation menus, though the route remains active and accessible via direct URL.
exclude: true: Completely removes the page from both development and build processes. When applied to a directory index.mdx, the entire directory is excluded.
Files or directories beginning with _ or . are ignored by the system.

MDX Runtime Helpers

2026-08-08T06:18:31.502Z

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/Rsbuild 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 the configured site/Rsbuild 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.

Links and Navigation

2026-06-25T22:36:39.961Z

Methanol utilizes a file-based routing mechanism. Internal links can be created simply by referencing the route path of the target file.

Internal Links

Reference site routes without file extensions:

[Writing Basics](./writing)

Rendered result: Writing Basics

If a page is moved or renamed, ensure that any links pointing to it are updated accordingly.

Subpath Deployments (`site.base`)

If your site is hosted under a subpath (e.g., https://example.com/docs/), ensure site.base: '/docs/' is configured. In such cases, avoid using root-absolute links like /blog/post within your content.

Relative linking is recommended:

[Next post](./next-post)
[Back to blog](../blog/)

If you need to generate a root-absolute link within MDX or JSX, wrap the path with ctx.withBase:

<a href={ctx.withBase('/blog/post')}>Read</a>

External Links

For external destinations, use fully qualified URLs:

[Example](https://example.com)

Rendered result: Example

Use Frontmatter properties to control the configured order and visibility of pages:

weight: Lower numerical values are positioned higher in the navigation.
hidden: Excludes the page from the sidebar menu.
isRoot: Defines an index.mdx file as the root of a navigation sub-tree.

For complete specifications, refer to the Frontmatter Reference.

Methanol Docs

Using Components

Using Components

Component Creation

Utilization in MDX

Client-side Interactivity

Interactive Example: Counter

Configuration

Configuration

Configuration Schema

Core Options

root

site

pagefind

feed

pwa

starryNight

jobs

gfm

pagesDir

componentsDir

publicDir

distDir

buildDir

intermediateDir

emitIntermediate

theme

mdx

rsbuild

Build Hooks

CLI Overrides

Implementation Example

Quick Start

Quick Start

Instant Preview

Using an Existing Directory

Installation

Production Workflow

Advanced Build Example

Project Structure

Creating Your First Page

CLI

CLI

Core Commands

Flag Reference

Execution via Node

Offline Access (PWA)

Offline Access (PWA)

Enabling PWA

Manifest Customization

Advanced Configuration

Custom Offline Page

Special-Purpose Pages

Special-Purpose Pages

Theme-Provided Pages

Differentiated Layouts

Interactive Components

Standalone HTML Pages

Path and Asset Resolution

Themes

Themes

Theme Implementation Guide

Theme Shape

Required

Defaults and Validation

Theme Layout Files

Template Contract

Theme Components

Theme Pages

Theme Public Assets

Theme Sources

Theme Hooks

Routing

Routing

MDX and Markdown Pages

.html Pages

404 Page

Offline Page

Hidden vs. Excluded

MDX Runtime Helpers

`root`

`site`

`pagefind`

`feed`

`pwa`

`starryNight`

`jobs`

`gfm`

`pagesDir`

`componentsDir`

`publicDir`

`distDir`

`buildDir`

`intermediateDir`

`emitIntermediate`

`theme`

`mdx`

`rsbuild`

`.html` Pages

Subpath Deployments (`site.base`)