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:

Core Options

root

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

site

Site-wide metadata utilized by templates:

Notes:

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:

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:

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:

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
}

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

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:

  1. Built-in Themes: Matches against Methanol's internal themes (e.g., default, blog).
  2. 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.

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.

Hook Context:

Build-only hooks additionally receive:

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:

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()]
	})
})