Methanol Docs

Welcome

2026-06-19T22:36:06.586Z

Welcome to Methanol!

Methanol is an opinionated, fully customizable static site generator powered by rEFui and MDX. Designed for speed and clarity, it provides a streamlined environment for technical writing and creative ideas.

Methanol requires nearly zero configuration: simply place your files in pages/ (or docs/) to automatically generate routes, a homepage from index.mdx, and a complete navigation tree.

Core Features

Automated Routing: Drop MDX files into content directories and let Methanol handle the routing and navigation.
Component Integration: Author reusable JSX components in components/ and embed them directly within your Markdown.
Fine-grained Control: Manage navigation hierarchy, ordering, and visibility using standard frontmatter.
Production Ready: Build to optimized static files in dist/ with built-in preview capabilities.
Extensible Pipeline: Easily integrate Pagefind for search and Starry Night for syntax highlighting.

rEFui: HTML + Islands

Methanol leverages rEFui for both server-side HTML generation and client-side interactivity. The majority of your site is shipped as pure static HTML; only interactive client components are hydrated as isolated "islands" where necessary, avoiding the overhead of full-page hydration.

Quick Start

2026-06-19T22:36:06.586Z

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:5173 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

Custom Components

2026-06-19T22:36:06.586Z

Custom Components

Methanol loads components from components/ and makes them available in every MDX file. Components are rendered with rEFui, so you can rely on its JSX runtime and APIs when building custom UI.

Component Discovery

Files can be .jsx, .tsx, .js, or .ts.
The file name becomes the component name.
User components override theme components with the same name.

Example:

components/
  Callout.jsx
  Hero.client.jsx
  Toc.static.jsx

Client-Only Components

Use the .client suffix to mark components that should only run on the client. This is useful for components that rely on browser APIs.

components/ThemeSearch.client.jsx

Static Components

Use the .static suffix for components that should be evaluated at build time.

If a client-only component does not have a server/static counterpart, Methanol will try to statically render the client component. If the client component uses browser-only APIs, you must provide a corresponding static component for server rendering.

components/Notice.static.jsx

Importing and Using

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

<Callout title="Tip">
  Keep paragraphs short for scannable docs.
</Callout>

Advanced

2026-06-19T22:36:06.586Z

Advanced

This section is dedicated to theme developers, component authors, and users seeking deep control over the rendering logic and architectural patterns of their site.

Key Topics

MDX Runtime Helpers

2026-06-19T22:36:06.586Z

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.

rEFui Runtime

2026-06-19T22:36:06.586Z

rEFui Runtime

Methanol uses rEFui as its JSX runtime. You do not need to learn rEFui to write docs, but it is useful for theme and component authors who want to build richer UI.

Methanol uses rEFui on both sides:

Server/SSG: render JSX to HTML during build (and on the dev server).
Client: hydrate only client components as small “islands”, leaving the rest of the page as static HTML.

When It Matters

Writing custom templates (theme.template)
Building interactive components in components/
Using rawHTML and context helpers

JSX Runtime

Methanol compiles MDX with the automatic JSX runtime and refui as the import source. You can still write standard JSX components.

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

Component Demo (Web)

If you want to experiment with rEFui outside Methanol, use the DOM renderer with a small reactive component:

import { signal } from 'refui'
import { createDOMRenderer } from 'refui/dom'
import { defaults } from 'refui/browser'

const DOMRenderer = createDOMRenderer(defaults)

const App = () => {
	const count = signal(0)
	const increment = () => {
		count.value += 1
	}

	return (R) => (
		<>
			<h1>Hello, rEFui</h1>
			<button on:click={increment}>Click me! Count is {count}</button>
			<p>Double: {$(() => count.value * 2)}</p>
		</>
	)
}

DOMRenderer.render(document.body, App)

In Methanol, you typically export components and let the MDX renderer handle mounting.

Reference

See the rEFui repository for detailed runtime and renderer documentation.

Theme Guide

2026-06-19T22:36:06.586Z

Theme Guide

This guide provides a comprehensive walkthrough for building a custom Methanol theme. You will learn how to implement core features such as navigation, tables of contents, and multi-language support, while adhering to Methanol's theme architecture.

Recommended Directory Structure

A standard theme typically follows this structure:

index.js: Theme object entry point.
page.jsx: Main layout template component.
components/: Default MDX components (optional).
pages/: Theme-provided pages (optional).
public/: Theme-specific static assets (optional).
sources/: Asset mappings via theme.sources (optional).

Theme Configuration

To enable a custom theme, specify its root directory and template component in methanol.config.js:

import PageTemplate from './theme/page.jsx'

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

Theme Object Definition

A theme can also be defined as an object in its entry point (index.js). This is particularly useful for distributive themes:

import PageTemplate from './page.jsx'

export default () => ({
	theme: {
		root: '.',
		template: PageTemplate,
		componentsDir: './components',
		pagesDir: './pages',
		publicDir: './public',
		sources: {
			'/theme': './sources'
		}
	}
})

Publishing and Resolution

Themes can be published as npm packages named methanol-theme-xxx. Methanol automatically resolves theme names using the following priority:

Built-in Themes: Internal presets (e.g., default, blog).
Package Resolution: Searches for methanol-theme-xxx.

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

Using a Published Theme

Via CLI:

methanol build --theme xxx

Via methanol.config.js:

export default () => ({
	theme: 'xxx'
})

Template Specification

The theme.template function receives a context object with the following properties:

ctx: Site and page context.
page: Alias for ctx.page.
PageContent: Renders the current page body.
ExtraHead: Injects runtime scripts, styles, and per-page <Head> content.
withBase: Base-path aware URL helper.
components: Merged set of theme and user components.
HTMLRenderer: rEFui rendering utilities.

Minimal Implementation

import { HTMLRenderer } from 'methanol'

export default ({ PageContent, ExtraHead, ctx }) => (
	<>
		{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>
			</head>
			<body>
				<PageContent />
			</body>
		</html>
	</>
)

For production-ready themes, refer to the following specialized guides:

Language Switcher

2026-06-19T22:36:06.586Z

Language Switcher

In Methanol, multi-language support is file-system based. Any directory containing an index.mdx with a lang property in its frontmatter is identified as a language entry point.

Your theme template receives the following language-related properties:

ctx.languages: A list of all identified language entry points.
ctx.language: The language entry point corresponding to the current page (or null).

Each entry includes routePath, routeHref, label, and code.

A standard implementation using a <select> element:

const LanguageSwitch = ({ ctx }) => {
	const languages = ctx.languages || []
	if (languages.length === 0) return null

	const currentHref = ctx.language?.routeHref
	return (
		<select
			aria-label="Select language"
			onchange="location.href=this.value"
			value={currentHref || undefined}
		>
			{languages.map((lang) => (
				<option value={lang.routeHref} selected={lang.routeHref === currentHref ? true : null}>
					{lang.label}
				</option>
			))}
		</select>
	)
}

Link List Variant

A list-based implementation suitable for footers or headers:

const LanguageLinks = ({ ctx }) => {
	const languages = ctx.languages || []
	if (languages.length === 0) return null

	const currentHref = ctx.language?.routeHref
	return (
		<nav aria-label="Language selection">
			{languages.map((lang) => (
				<a href={lang.routeHref} aria-current={lang.routeHref === currentHref ? 'page' : null}>
					{lang.label}
				</a>
			))}
		</nav>
	)
}

Implementation Notes

URL Handling: Always use routeHref for links to ensure they are base-path aware.
Root Scoping: It is common to set isRoot: true at each language's entry point to maintain independent navigation trees for each language.

Rendering Navigation

2026-06-19T22:36:06.586Z

Methanol provides a hierarchical navigation tree via ctx.pagesTree. This tree is automatically scoped to the current navigation root (isRoot) and respects all hidden and exclude rules.

Each node in the tree uses the following structure:

{
	type: 'page' | 'directory',
	title: '...',
	name: '...',
	routePath: '/guide/',
	routeHref: '/docs/guide/', // Base-aware URL
	children: []
}

The following example demonstrates a recursive sidebar component:

const NavTree = ({ nodes, currentHref }) => (
	<ul>
		{(nodes || []).map((node) => {
			const label = node.title || node.name || node.routePath
			if (node.type === 'directory') {
				return (
					<li>
						{node.routeHref ? <a href={node.routeHref}>{label}</a> : <span>{label}</span>}
						{node.children?.length ? <NavTree nodes={node.children} currentHref={currentHref} /> : null}
					</li>
				)
			}
			const isActive = node.routeHref === currentHref
			return (
				<li>
					<a href={node.routeHref} aria-current={isActive ? 'page' : null}>
						{label}
					</a>
				</li>
			)
		})}
	</ul>
)

export default function PageTemplate({ PageContent, ExtraHead, ctx }) {
	return (
		<>
			<html>
				<head>
					<ExtraHead />
				</head>
				<body>
					<aside>
						<NavTree nodes={ctx.pagesTree} currentHref={ctx.page.routeHref} />
					</aside>
					<main>
						<PageContent />
					</main>
				</body>
			</html>
		</>
	)
}

Best Practices

Use routeHref: Always use routeHref for navigation links to ensure the site.base prefix is correctly applied.
Trailing Slashes: Directory index routes always include a trailing slash in their routePath (e.g., /guide/). This is important for path matching and relative link resolution.

Adjacent Page Links

2026-06-19T22:36:06.586Z

Adjacent Page Links

Methanol provides a helper to implement "Previous" and "Next" navigation, ensuring users can traverse your documentation in the intended order:

const { prev, next } = ctx.getSiblings() || {}

The returned sequence is automatically scoped to the current navigation root and respects the sidebar's display order.

Implementation Example

const PrevNext = ({ ctx }) => {
	const siblings = ctx.getSiblings()
	const prev = siblings?.prev
	const next = siblings?.next
	if (!prev && !next) return null

	return (
		<nav aria-label="Pagination">
			{prev ? <a href={prev.routeHref}>← {prev.title}</a> : <span />}
			{next ? <a href={next.routeHref}>{next.title} →</a> : <span />}
		</nav>
	)
}

export default function PageTemplate({ PageContent, ExtraHead, ctx }) {
	return (
		<>
			<html>
				<head>
					<ExtraHead />
				</head>
				<body>
					<main>
						<PageContent />
						<PrevNext ctx={ctx} />
					</main>
				</body>
			</html>
		</>
	)
}

Best Practices

Base Path Awareness: Use routeHref for all pagination links to ensure they work correctly with site.base.
Filtering: Pages marked as hidden: true are automatically excluded from the sibling sequence, maintaining a clean navigation flow.

Methanol Docs

Welcome

Welcome to Methanol!

Core Features

rEFui: HTML + Islands

Quick Start

Quick Start

Instant Preview

Using an Existing Directory

Installation

Production Workflow

Advanced Build Example

Project Structure

Creating Your First Page

Custom Components

Custom Components

Component Discovery

Client-Only Components

Static Components

Importing and Using

Advanced

Advanced

Key Topics

MDX Runtime Helpers

MDX Runtime Helpers

Context Variables

Context Structure

ctx.site

ctx.page Metadata Object

ctx.pages List

ctx.pagesTree Hierarchy

ctx.getSiblings Helper

rawHTML Utility

rEFui Runtime

rEFui Runtime

When It Matters

JSX Runtime

Component Demo (Web)

Reference

Theme Guide

Theme Guide

Recommended Directory Structure

Theme Configuration

Theme Object Definition

Publishing and Resolution

Using a Published Theme

Template Specification

Minimal Implementation

Language Switcher

Language Switcher

Dropdown Switcher Implementation

Link List Variant

Implementation Notes

Rendering Navigation

Rendering Navigation

Sidebar Implementation

Best Practices

Adjacent Page Links

Adjacent Page Links

Implementation Example

Best Practices