Methanol

https://methanol.sudomaker.com
Admin
Methanol is an opinionated, fully customizable static site generator powered by rEFui and MDX,...
Tokens:20,578
Snippets:229
Trust Score:5.3
Update:9 months ago
Show doc for...
Tokens:
Raw
### Serve Methanol Production Build Locally

Source: https://methanol.sudomaker.com/quick-start

Starts a local web server to preview the production build of your Methanol site. This is useful for testing the final output before deploying it.

```bash
npx methanol serve

```

--------------------------------

### Methanol CLI Commands with npx

Source: https://methanol.sudomaker.com/reference/cli

Demonstrates how to use the Methanol CLI with npx for starting the development server, building the project, and serving the production build. These commands are the quickest way to get started without global installation.

```bash
npx methanol dev      # start dev server
npx methanol build    # build to dist/
npx methanol serve    # serve the production build
```

--------------------------------

### Run Methanol Development Server with Existing Docs Folder

Source: https://methanol.sudomaker.com/quick-start

Starts the Methanol development server, pointing it to an existing folder containing your Markdown or MDX files. This allows you to use Methanol with your pre-existing documentation structure, mapping the specified folder as the content root.

```bash
npx methanol dev ./my-docs

```

--------------------------------

### Install Methanol Globally and Run Development Server

Source: https://methanol.sudomaker.com/quick-start

Installs Methanol globally on your system, allowing you to run the `methanol` command directly without `npx`. This provides a faster CLI startup for local development workflows.

```bash
npm install methanol -g
methanol dev

```

--------------------------------

### Create First Page in Methanol

Source: https://methanol.sudomaker.com/quick-start

Demonstrates the creation of the initial `index.mdx` file for the homepage of a Methanol site. It shows the front matter for setting metadata like the title and the basic content structure.

```markdown
---
title: Home
---

# Welcome

This is my site.

```

--------------------------------

### Run Methanol Development Server Locally

Source: https://methanol.sudomaker.com/quick-start

Starts the Methanol development server for a quick local preview. It automatically watches for changes in your Markdown/MDX files and rebuilds the site. The default development server runs on http://localhost:5173.

```bash
npx methanol dev

```

--------------------------------

### Build Methanol Site for Production

Source: https://methanol.sudomaker.com/quick-start

Generates the production-ready static files for your website. The output is typically placed in a `dist/` folder, optimized for deployment.

```bash
npx methanol build

```

--------------------------------

### Build Static Site with Methanol CLI

Source: https://methanol.sudomaker.com/guide/publishing

This command builds the static site, outputting the files to the `dist/` directory. No external dependencies are required beyond the Methanol CLI installation.

```bash
npx methanol build
```

--------------------------------

### Global Methanol CLI Installation and Usage

Source: https://methanol.sudomaker.com/reference/cli

Explains how to install the Methanol CLI globally using npm for faster startup and then run its commands directly. This is useful for frequent use across multiple projects.

```bash
npm install methanol -g
methanol dev
```

--------------------------------

### Install Pagefind Globally (npm)

Source: https://methanol.sudomaker.com/reference/search

Installs Pagefind globally on your system using npm, making it available as a command-line tool.

```bash
npm i -g pagefind
```

--------------------------------

### Install Pagefind Locally (npm)

Source: https://methanol.sudomaker.com/reference/search

Installs Pagefind as a development dependency in your project using npm.

```bash
npm i -D pagefind
```

--------------------------------

### Example Directory Structure for Multi-language

Source: https://methanol.sudomaker.com/reference/languages

Demonstrates a typical file structure for a multi-language setup in Methanol. Each language has its own directory containing an index file and other content pages.

```tree
pages/
  index.mdx          # root language
  zh/
    index.mdx        # Chinese language root
    guide.mdx
  fr/
    index.mdx        # French language root
    guide.mdx
```

--------------------------------

### Install Pagefind Search

Source: https://methanol.sudomaker.com/advanced/themes/default

Installs the Pagefind search library as a development dependency. This is required to enable the search functionality within the Methanol theme.

```bash
npm i -D pagefind

```

--------------------------------

### Theme Configuration Example

Source: https://methanol.sudomaker.com/reference/configuration

Configure the project theme, including the theme root directory, custom HTML templates, default MDX components, and theme-specific directories for components, pages, and public assets.

```javascript
theme: {
  root: 'path/to/theme',
  template: ({ ctx, page, PageContent, ExtraHead, withBase, HTMLRenderer, components }) => {
    // custom template logic
  },
  components: {
    // default MDX components
  },
  componentsDir: 'theme/components',
  pagesDir: 'theme/pages',
  publicDir: 'theme/public',
  sources: { /* virtual file map */ },
  mdx: { /* default MDX options */ },
  vite: { /* default Vite config */ }
}
```

--------------------------------

### Preview Production Output Locally with Methanol CLI

Source: https://methanol.sudomaker.com/guide/publishing

This command serves the production-ready static site locally, allowing verification of the output generated by `npx methanol build`. It's useful for testing before deployment.

```bash
npx methanol serve
```

--------------------------------

### Build Pipeline Hooks Example

Source: https://methanol.sudomaker.com/reference/configuration

Demonstrates the implementation of preBuild, preBundle, and postBuild hooks to customize build processes. These hooks allow for custom logic before building, before bundling, and after building, respectively. They can access shared data and information about the site and pages.

```javascript
export default () => ({
	preBuild: ({ data, site }) => {
		data.startedAt = Date.now()
		console.log('Building', site.name)
	},
	preBundle: ({ pages }) => {
		console.log('Rendered pages:', pages.length)
	},
	postBuild: ({ data, pages }) => {
		console.log('Duration (ms):', Date.now() - data.startedAt)
		console.log('Pages:', pages.length)
	}
})
```

--------------------------------

### Methanol CLI Dev with Input Directory Argument

Source: https://methanol.sudomaker.com/reference/cli

Illustrates how to specify only the input directory for the Methanol dev command. In development mode, only the input directory is used to start the dev server.

```bash
npx methanol dev ./pages
```

--------------------------------

### Example Frontmatter for Language Root

Source: https://methanol.sudomaker.com/reference/languages

Illustrates the frontmatter configuration for a language root index page. Key fields like 'lang', 'langCode', and 'isRoot' are used to define language properties.

```yaml
---
title: 简体中文
lang: 简体中文
langCode: zh
isRoot: true
hidden: true
---

```

--------------------------------

### rEFui Reactive Component Demo (Browser)

Source: https://methanol.sudomaker.com/advanced/refui

Demonstrates a small, reactive component using rEFui in a browser environment. It utilizes signals for state management and DOM rendering. This example is useful for experimenting with rEFui outside of Methanol.

```javascript
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)
```

--------------------------------

### Local Image Usage in MDX

Source: https://methanol.sudomaker.com/guide/assets

Illustrates how to link to an image file that is located in the same directory as an MDX page using a relative path. This is useful for page-specific diagrams or assets.

```markdown
![Diagram](./writing-diagram.png)
```

--------------------------------

### Running Methanol CLI Directly with Node

Source: https://methanol.sudomaker.com/reference/cli

Provides an alternative method to run the Methanol CLI commands by directly executing the script using Node. This approach bypasses npx and global installations.

```bash
node node_modules/methanol/bin/methanol.js dev
```

--------------------------------

### Install vite-plugin-pwa

Source: https://methanol.sudomaker.com/guide/offline

Install the vite-plugin-pwa package as a development dependency using npm. This command adds the necessary plugin to your project's development environment.

```bash
npm install vite-plugin-pwa -D

```

--------------------------------

### Configuration with Vite Plugins and Theme

Source: https://methanol.sudomaker.com/reference/configuration

An example configuration object for Methanol Sudomaker, showcasing site configuration, theme customization including HTML template and components, MDX options, and Vite integration with plugins like tailwindcss. This configuration demonstrates how to set up the development server port and customize the build output.

```javascript
import tailwindcss from '@tailwindcss/vite'

export default ({ mode }) => ({
	site: { name: 'My 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>Hi</components.Callout> : null}
						<PageContent />
					</body>
				</html>
			</>
		),
		components: {
			Callout: ({ children }) => <div class="callout">{children}</div>
		}
	},
	mdx: () => ({
		development: mode !== 'production'
	}),
	vite: () => ({
		server: { port: 5173 },
		plugins: [tailwindcss()]
	})
})
```

--------------------------------

### Add Extra Languages to Starry Night (JavaScript)

Source: https://methanol.sudomaker.com/reference/code-highlighting

Extend Starry Night's language support by importing additional grammars, such as `sourceMDX`, and including them in the `starryNight.grammars` configuration. Ensure `@wooorm/starry-night` is installed.

```javascript
import { common } from '@wooorm/starry-night'
import sourceMDX from '@wooorm/starry-night/source.mdx'

export default () => ({
	starryNight: {
		grammars: [...common, sourceMDX]
	}
})
```

--------------------------------

### Global Styles and Scripts Injection

Source: https://methanol.sudomaker.com/guide/assets

Shows how to include global CSS and JavaScript files by placing them in the `pages/` directory. Methanol automatically injects these into every page. The provided HTML snippet represents how these would be linked.

```html
<link rel="stylesheet" href="/style.css" />
<script type="module" src="/index.js"></script>
```

--------------------------------

### Component File Structure Example

Source: https://methanol.sudomaker.com/advanced/components

Illustrates the directory structure for custom components in Methanol. Files with .jsx, .tsx, .js, or .ts extensions in the 'components/' directory are automatically discovered. The file name determines the component name, and user components override theme components with the same name.

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

--------------------------------

### Injecting Unescaped HTML using rawHTML

Source: https://methanol.sudomaker.com/advanced/mdx-runtime

This snippet demonstrates the use of the `rawHTML` helper function to inject HTML content directly into the MDX output without escaping. It shows examples using both string literals and template literals.

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

```

--------------------------------

### Get Previous/Next Links with Methanol

Source: https://methanol.sudomaker.com/advanced/theme-guide/prev-next

Retrieves previous and next sibling page objects from the context. Returns an object with `prev` and `next` properties, or null if no siblings are found. Useful for implementing navigation.

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

```

--------------------------------

### Public Folder Asset Usage in MDX

Source: https://methanol.sudomaker.com/guide/assets

Demonstrates how to reference assets placed in the `public/` directory within MDX files using Markdown image syntax and standard link syntax. These assets are served from the site root.

```markdown
![Logo](/logo.png)
[Download the brochure](/downloads/brochure.pdf)
```

--------------------------------

### Exporting a Custom Component (JSX)

Source: https://methanol.sudomaker.com/advanced/components

Provides an example of how to export a default function component named 'Callout' using JSX. This component accepts a 'title' prop and renders a div with the title and children.

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

--------------------------------

### Configure Methanol for Subpath Deployment

Source: https://methanol.sudomaker.com/guide/publishing

This configuration snippet allows setting a base subpath for the deployed static site. It's used in `methanol.config.*` files to specify the site's base URL if it's not served from the root.

```javascript
export default () => ({
	site: {
		base: '/docs/'
	}
})
```

--------------------------------

### Methanol Theme Object Export with Multiple Directories

Source: https://methanol.sudomaker.com/advanced/theme-guide

Defines the theme object in index.js, specifying the root directory, template component, and directories for components, pages, public assets, and sources. It also includes configuration for asset sources.

```javascript
import PageTemplate from './page.jsx'

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

--------------------------------

### Fenced Code Block with Language Identifier

Source: https://methanol.sudomaker.com/guide/writing

Shows how to embed code blocks in Markdown using fenced code blocks with a language identifier for syntax highlighting. This is useful for showcasing code examples.

```markdown
```js
export const title = 'Hello'
```

```

--------------------------------

### Integrate Custom Highlighter (JavaScript)

Source: https://methanol.sudomaker.com/reference/code-highlighting

Replace Starry Night with a custom highlighter by disabling Starry Night (`starryNight: false`) and adding your plugin to the `mdx.rehypePlugins` configuration. This requires installing and configuring your chosen highlighter.

```javascript
export default () => ({
	starryNight: false,
	mdx: () => ({
		rehypePlugins: [/* your highlighter */]
	})
})
```

--------------------------------

### Minimal Methanol Theme Template Component

Source: https://methanol.sudomaker.com/advanced/theme-guide

A basic implementation of a Methanol theme template component. It renders the essential HTML structure, including head content and the main page body, using provided props like PageContent and ExtraHead.

```javascript
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>
	</>
)
```

--------------------------------

### Define a Basic JSX Component with rEFui

Source: https://methanol.sudomaker.com/advanced/refui

Example of defining a simple functional component using JSX syntax, compatible with Methanol's rEFui integration. This component takes props and children to render a div with a 'callout' class.

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

--------------------------------

### React Simple Select Language Switcher

Source: https://methanol.sudomaker.com/advanced/theme-guide/language-switch

A React component that renders a `<select>` element for users to switch between available languages. It utilizes the `ctx.languages` and `ctx.language` from the Methanol context to populate options and set the current selection. Dependencies include React.

```jsx
const LanguageSwitch = ({ ctx }) => {
	const languages = Array.isArray(ctx.languages) ? ctx.languages : []
	if (!languages.length) return null
	const currentHref = ctx.language?.routeHref || null
	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>
	)
}

```

--------------------------------

### Configure vite-plugin-pwa in methanol.config.js

Source: https://methanol.sudomaker.com/guide/offline

Configure vite-plugin-pwa within your methanol.config.js file. This setup enables offline access by caching specified assets and setting a fallback for undefined routes.

```javascript
import { VitePWA } from 'vite-plugin-pwa'

export default () => ({
	vite: {
		plugins: [
			VitePWA({
				injectRegister: 'auto',
				registerType: 'autoUpdate',
				workbox: {
					globPatterns: ['**/*.{js,css,html,ico,png,svg}'],
					navigateFallback: '/404.html',
					ignoreURLParametersMatching: [/./]
				}
			})
		]
	}
})

```

--------------------------------

### Methanol CLI Build with Positional Arguments

Source: https://methanol.sudomaker.com/reference/cli

Shows how to specify input and output directories as positional arguments for the Methanol build command. The order of these arguments is important: input directory first, then output directory.

```bash
npx methanol build ./pages ./dist
```

--------------------------------

### Generating a List of All Pages using ctx.pages

Source: https://methanol.sudomaker.com/advanced/mdx-runtime

This snippet illustrates how to iterate over all available pages in the project using `ctx.pages`. It generates an unordered list where each list item contains a link to a page, displaying its title. It prioritizes `routeHref` for links, falling back to `routePath`.

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

```

--------------------------------

### Displaying Previous and Next Page Links using ctx.getSiblings

Source: https://methanol.sudomaker.com/advanced/mdx-runtime

This snippet utilizes `ctx.getSiblings()` to retrieve the previous and next pages in the current navigation sequence. It conditionally renders navigation links for 'Previous' and 'Forward' pages if they exist, displaying their titles.

```mdx
{(() => {
  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}>Forward: {siblings.next.title}</a> : null}
    </nav>
  )
})()}

```

--------------------------------

### Conditional Logic for Page Branching

Source: https://methanol.sudomaker.com/advanced/theme-guide/special-pages

Provides examples of conditional logic to determine page rendering or layout. This includes checking file type, route path, or specific frontmatter values to adapt the output.

```plaintext
Common patterns:
  * Branch by file type: `ctx.page.filePath.endsWith('.html')`
  * Branch by route: `ctx.page.routePath === '/menu'`
  * Branch by frontmatter: `ctx.page.frontmatter?.layout === 'landing'`
```

--------------------------------

### Rendering Navigation Tree Nodes using ctx.pagesTree

Source: https://methanol.sudomaker.com/advanced/mdx-runtime

This snippet demonstrates how to map through the `ctx.pagesTree` structure to display navigation nodes. It shows the title or name of each node, which can represent either a page or a directory in the site's hierarchy.

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

```

--------------------------------

### Methanol Theme Configuration with JSX Template

Source: https://methanol.sudomaker.com/advanced/theme-guide

Configures the Methanol theme by specifying the root directory and providing a JSX template component. This typically involves importing a custom PageTemplate and setting it in the theme configuration.

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

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

--------------------------------

### Displaying Page Title and Route Path using ctx

Source: https://methanol.sudomaker.com/advanced/mdx-runtime

This snippet demonstrates how to access and display the page's title and current route path using the `ctx` object. It utilizes frontmatter for the title if available, otherwise falling back to the page's default title.

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

Current route: {ctx.routePath}

```

--------------------------------

### Client-Only Component Naming Convention

Source: https://methanol.sudomaker.com/advanced/components

Demonstrates how to mark a component to run exclusively on the client using the '.client' suffix. This is essential for components that depend on browser-specific APIs.

```directory
components/ThemeSearch.client.jsx
```

--------------------------------

### Markdown Body Text Formatting

Source: https://methanol.sudomaker.com/guide/writing

Demonstrates how to format body text in Markdown, including paragraph separation, line breaks, and forced line breaks using trailing spaces or HTML.

```markdown
First paragraph line 1
First paragraph line 2 (usually merges into the same paragraph)

Second paragraph
This line has two trailing spaces  
so it breaks

```

--------------------------------

### Configure Pagefind Options in Methanol

Source: https://methanol.sudomaker.com/reference/search

Configures advanced options for Pagefind, including enabling it, setting excerpt length, and specifying build output subdirectory and verbosity in methanol.config.js.

```javascript
export default () => ({
	pagefind: {
		enabled: true,
		excerptLength: 30,
		build: {
			outputSubdir: 'pagefind',
			verbose: true
		}
	}
})
```

--------------------------------

### Displaying Current Page Title and Excerpt using ctx.page

Source: https://methanol.sudomaker.com/advanced/mdx-runtime

This snippet shows how to access specific page metadata, such as the title and excerpt from frontmatter, using the `ctx.page` object. The `?.` operator is used for safe access to the optional `excerpt` property.

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

```

--------------------------------

### Using a Custom Component in MDX

Source: https://methanol.sudomaker.com/advanced/components

Demonstrates how to import and use the custom 'Callout' component within an MDX file. The component is rendered with the provided 'title' prop and its children.

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

--------------------------------

### Static Component Naming Convention

Source: https://methanol.sudomaker.com/advanced/components

Shows how to designate a component to be evaluated at build time using the '.static' suffix. This is crucial for server-side rendering when a client-only component lacks a static counterpart or uses browser-only APIs.

```directory
components/Notice.static.jsx
```

--------------------------------

### Enable Pagefind Search in Methanol Config

Source: https://methanol.sudomaker.com/reference/search

Enables the Pagefind static search functionality by setting the 'pagefind' option to true in the methanol.config.js file.

```javascript
// methanol.config.js
export default () => ({
	pagefind: true
})
```

--------------------------------

### React Link List Language Switcher

Source: https://methanol.sudomaker.com/advanced/theme-guide/language-switch

A React component that generates an accessible navigation list of links for language switching. It iterates through `ctx.languages` to create `<a>` tags, highlighting the current language using `aria-current='page'`. This component relies on React and the Methanol context.

```jsx
const LanguageLinks = ({ ctx }) => {
	const languages = Array.isArray(ctx.languages) ? ctx.languages : []
	if (!languages.length) return null
	const currentHref = ctx.language?.routeHref
	return (
		<nav aria-label="Languages">
			{languages.map((lang) => (
				<a href={lang.routeHref} aria-current={lang.routeHref === currentHref ? 'page' : null}>
					{lang.label}
				</a>
			))}
		</nav>
	)
}

```

--------------------------------

### Map Virtual URLs to Files - JavaScript

Source: https://methanol.sudomaker.com/advanced/themes

This code snippet illustrates how to configure theme sources in Methanol. It defines a mapping where virtual URLs (e.g., '/theme') are associated with specific file paths on the filesystem (e.g., './sources'). This mechanism is handled by Methanol's resolver and allows for the use of virtual assets within the theme.

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

--------------------------------

### Render Prev/Next Navigation Links with React

Source: https://methanol.sudomaker.com/advanced/theme-guide/prev-next

A React component that uses the `ctx.getSiblings()` helper to fetch previous and next page data and render navigation links. It conditionally displays links if `prev` or `next` siblings exist. Requires `ctx` object as a prop.

```javascript
const PrevNext = ({ ctx }) => {
	const siblings = ctx.getSiblings()
	const prev = siblings?.prev
	const next = siblings?.next
	if (!prev && !next) return null
	return (
		<nav aria-label="Page navigation">
			{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>
		</>
	)
}

```

--------------------------------

### Relative Internal Links for Subpath Deployments

Source: https://methanol.sudomaker.com/guide/links

When deploying a site under a subpath (e.g., `/docs/`), use relative internal links to maintain correct navigation. This avoids issues with root-absolute links.

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

```

--------------------------------

### Define Theme Structure and Template - JavaScript/JSX

Source: https://methanol.sudomaker.com/advanced/themes

This snippet demonstrates how to define the overall structure of a Methanol theme, including root directories, component paths, and public asset locations. It also shows how to implement a custom HTML template, specifying the doctype, language, head content, and body structure, including the integration of page content and user-defined components.

```javascript
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>
		}
	}
})
```

--------------------------------

### Configuration Function Export

Source: https://methanol.sudomaker.com/reference/configuration

The configuration file must export a default function that accepts a context object and returns a configuration object. The context provides information about the build mode, project root, and HTML rendering utilities.

```javascript
export default ({ mode, root, HTMLRenderer }) => ({
	// config values
})
```

--------------------------------

### Use a Callout Component in MDX

Source: https://methanol.sudomaker.com/guide/components

Demonstrates how to embed the 'Callout' component directly within an MDX file. This allows for easily displaying formatted tips or important information.

```mdx
<Callout>
  Tip: Keep sections short and focused.
</Callout>
```

--------------------------------

### Per-Page Code Highlighting Override (YAML Frontmatter)

Source: https://methanol.sudomaker.com/reference/code-highlighting

Override the global code highlighting setting for individual pages by specifying `starryNight: true` or `starryNight: false` in the page's frontmatter. This takes precedence over the configuration file.

```yaml
---
starryNight: true
---
```

--------------------------------

### Markdown Blockquote Formatting

Source: https://methanol.sudomaker.com/guide/writing

Illustrates the use of blockquotes in Markdown. Blockquotes are created using the '>' symbol, and blank lines within the quote can be maintained by using '>' on an empty line.

```markdown
> This is a blockquote.
> 
> Put `>` on an empty line to keep a blank line inside the same quote.
> Multiple quoted lines become one quote block.

> A blank line between `>` blocks creates a new quote block.

```

--------------------------------

### Methanol Configuration File Structure

Source: https://methanol.sudomaker.com/reference/configuration

Methanol looks for configuration files in your project root. Supported extensions include .js, .mjs, .cjs, .ts, .jsx, .tsx, .mts, and .cts.

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

--------------------------------

### Generating Root-Absolute Links in MDX/JSX

Source: https://methanol.sudomaker.com/guide/links

To generate root-absolute links within MDX or JSX files, especially when dealing with subpath deployments, wrap the path with the `ctx.withBase` helper function.

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

```

--------------------------------

### Basic Markdown Page Structure with Frontmatter

Source: https://methanol.sudomaker.com/guide/writing

Defines the basic structure of a Markdown page in Methanol, including frontmatter for metadata and the main content area. Frontmatter is used for SEO and navigation.

```markdown
---
title: My Page
excerpt: Short summary used in meta tags
---

# My Page

Write your content here.

```

--------------------------------

### Using Head Component in MDX

Source: https://methanol.sudomaker.com/reference/head

This snippet demonstrates how to use the `Head` component within an MDX file to add custom meta tags and canonical links to the document's `<head>`. The component is globally available and does not require explicit import.

```mdx
<Head>
	<meta name="description" content="My page description" />
	<link rel="canonical" href="https://example.com/docs/page" />
</Head>

```

--------------------------------

### Custom Vite Configuration

Source: https://methanol.sudomaker.com/reference/configuration

Merge custom Vite configurations into the project's build process. This function receives command, mode, root, and isPreview flags to conditionally apply settings.

```javascript
vite: ({ command, mode, root, isPreview }) => ({
  // Vite config options
})
```
Tokens:
Raw