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: