### Build and Serve Methanol Production Site
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/quick-start.mdx
Builds the optimized production output for your static site and then starts a local server to preview it. The production output is located in the 'dist/' directory.
```bash
npx methanol build
npx methanol serve
```
--------------------------------
### Run Methanol Dev Server
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/quick-start.mdx
Starts the Methanol development server for immediate testing. Navigate to http://localhost:5173 to view your site. This command assumes Methanol is installed locally via npx.
```bash
npx methanol dev
```
--------------------------------
### Run Methanol Dev Server with Custom Directory
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/quick-start.mdx
Starts the Methanol development server, pointing to a specific directory for content. Files in the specified folder (e.g., ./my-docs/index.mdx) are mapped to URL routes, with the root folder mapping to the site root (/).
```bash
npx methanol dev ./my-docs
```
--------------------------------
### Methanol Page Creation (MDX)
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/quick-start.mdx
Example of creating a basic MDX file for a Methanol page. The frontmatter (like 'title') is used for metadata, and the rest is rendered as content. This file structure automatically maps to URL routes.
```mdx
---
title: Home
---
# Welcome
This is my documentation site.
```
--------------------------------
### Install Pagefind Search
Source: https://context7.com/sudomaker/methanol-docs/llms.txt
Installing Pagefind as a development dependency using npm for static search functionality.
```bash
# Install Pagefind
npm install -D pagefind
```
--------------------------------
### Build Pipeline Hooks Example
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/reference/configuration.mdx
Demonstrates how to use `preBuild`, `preBundle`, and `postBuild` hooks to extend the Methanol build process. These hooks allow for custom logic execution at different stages of the build lifecycle, such as logging build information or duration. The example shows access to context data like `data`, `site`, and `pages`.
```javascript
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)
}
})
```
--------------------------------
### Methanol Configuration with Theming and Vite
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/reference/configuration.mdx
Provides an example of a Methanol configuration object. It showcases setting the site name, defining a custom HTML template within the theme, configuring MDX compilation based on the build mode, and integrating Tailwind CSS via Vite plugins. This example illustrates a comprehensive setup for a documentation site.
```javascript
import tailwindcss from '@tailwindcss/vite'
export default ({ mode }) => ({
site: { name: 'Technical Docs' },
theme: {
root: '.',
template: ({ PageContent, ExtraHead, ctx, withBase, HTMLRenderer, components }) => (
<>
{HTMLRenderer.rawHTML``}
{ctx.page.title || ctx.site.name}
{components.Callout ? Important Note : null}
),
components: {
Callout: ({ children }) =>
{children}
}
},
mdx: () => ({
development: mode !== 'production'
}),
vite: () => ({
server: { port: 5173 },
plugins: [tailwindcss()]
})
})
```
--------------------------------
### Install Pagefind for Search
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/advanced/themes/default.mdx
Installs Pagefind as a development dependency, enabling search functionality for the documentation site. This is a prerequisite for the Pagefind search UI integration.
```bash
npm i -D pagefind
```
--------------------------------
### Methanol CLI Global Installation Commands
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/reference/cli.mdx
Installs Methanol globally for system-wide access and executes commands. Offers improved performance and faster startup times compared to `npx`.
```bash
npm install methanol -g
methanol dev
```
--------------------------------
### Frontmatter Configuration Example
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/guide/page-ordering.mdx
Example of Frontmatter configuration for a page, defining its title and weight for navigation sorting. This Frontmatter is typically used in MDX files to control page ordering and display.
```mdx
---
title: Guides
weight: 10
---
```
--------------------------------
### Rendering Navigation Tree in JSX
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/advanced/mdx-runtime.mdx
Provides an example of how to render a navigation UI by mapping over the `ctx.pagesTree` hierarchy, displaying the title or name for each node.
```jsx
{ctx.pagesTree.map((node) => (
{node.title || node.name}
))}
```
--------------------------------
### MDX Page Structure Example
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/guide/writing.mdx
Demonstrates the basic structure of an MDX page, including frontmatter for metadata and the main content area. Frontmatter is crucial for page configuration and SEO.
```mdx
---
title: My Page
excerpt: Short summary used for meta tags
---
# My Page
Content goes here.
```
--------------------------------
### Minimum Template Implementation
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/advanced/theme-guide/index.mdx
Provides a basic implementation of a Methanol theme template, demonstrating how to use context, render page content, and inject dynamic head elements.
```jsx
import { HTMLRenderer } from 'methanol'
export default ({ PageContent, ExtraHead, ctx }) => (
<>
{HTMLRenderer.rawHTML``}
{ctx.page.title || ctx.site.name}
)
```
--------------------------------
### Serve Local Preview with Methanol CLI
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/guide/publishing.mdx
This command starts a local server to preview the production artifacts. It's essential for validating the site's appearance and functionality in a local environment before deploying it live.
```bash
npx methanol serve
```
--------------------------------
### Custom Theme Configuration in methanol.config.js
Source: https://context7.com/sudomaker/methanol-docs/llms.txt
Configuring a custom theme by defining the site name, repository base URL, and a custom HTML template. Includes example of a custom Callout component.
```javascript
// methanol.config.js
export default ({ mode, HTMLRenderer }) => ({
site: {
name: 'Technical Docs',
repoBase: 'https://github.com/owner/repo/edit/main/pages/'
},
theme: {
root: '.',
template: ({ PageContent, ExtraHead, ctx, withBase, HTMLRenderer, components }) => (
<>
{HTMLRenderer.rawHTML``}
{ctx.page.title || ctx.site.name}
),
components: {
Callout: ({ type }, ...children) => (
{...children}
)
}
}
})
```
--------------------------------
### MDX Content Writing Examples
Source: https://context7.com/sudomaker/methanol-docs/llms.txt
Demonstrates various MDX features including frontmatter, headings, text formatting, lists, blockquotes, code blocks, tables, task lists, JSX components, and links.
```mdx
---
title: Writing Guide
description: How to write effective documentation
weight: 1
date: 2025-01-15
starryNight: true
---
# Writing Guide
Standard paragraph text. Separate paragraphs with blank lines.
## Headings Generate TOC
`##`, `###`, and `####` headings appear in the table of contents.
## Text Formatting
**Bold text** and *italic text* and `inline code`.
## Lists
- Unordered item 1
- Unordered item 2
- Nested item
1. Ordered item 1
2. Ordered item 2
## Blockquotes
> This is a blockquote.
>
> Multiple paragraphs in the same block.
## Code Blocks
```javascript
// Syntax highlighted code
export default function hello() {
console.log('Hello, Methanol!')
}
```
## Tables (GFM)
| Feature | Status |
|---------|--------|
| Routing | ✅ |
| Search | ✅ |
| i18n | ✅ |
## Task Lists (GFM)
- [x] Completed task
- [ ] Pending task
## JSX in Markdown
Mix JSX components seamlessly with Markdown content.
## Links
[Internal link](./other-page)
[External link](https://example.com)
[Anchor link](#headings-generate-toc)
```
--------------------------------
### Theme Directory Structure
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/advanced/theme-guide/index.mdx
Illustrates the standard directory layout for a Methanol theme, including entry points, components, pages, and static assets.
```text
theme/
index.js # Theme object entry point
page.jsx # 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)
```
--------------------------------
### Configure Theme in methanol.config.js
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/advanced/theme-guide/index.mdx
Shows how to enable a custom theme in the methanol.config.js file by specifying the theme's root directory and the main template component.
```javascript
import PageTemplate from './theme/page.jsx'
export default () => ({
ttheme: {
root: './theme',
template: PageTemplate
}
})
```
--------------------------------
### Template Layout Switching Example
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/advanced/theme-guide/special-pages.mdx
A template implementation demonstrating how to conditionally render different layouts (e.g., MenuLayout, DocLayout) based on the 'layout' property in the page's frontmatter. It handles the structure for different page types.
```jsx
const MenuLayout = ({ ctx, PageContent }) => (
{ctx.page.title}
)
const DocLayout = ({ ctx, PageContent }) => (
)
export default function PageTemplate({ PageContent, ExtraHead, ctx }) {
const layout = ctx.page.frontmatter?.layout
return (
<>
{ctx.page.title || ctx.site.name}
{layout === 'menu' ? (
) : (
)}
)
}
```
--------------------------------
### ctx.languages Data Structure Example
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/reference/languages.mdx
Provides an example of an object within the `ctx.languages` array. This structure aggregates language information, including the `routePath`, `routeHref` for linking, a user-friendly `label`, and a language `code`. It's essential to use `routeHref` when generating links to ensure the `site.base` prefix is correctly applied.
```javascript
{
routePath: '/zh/',
routeHref: '/zh/',
label: '简体中文',
code: 'zh'
}
```
--------------------------------
### Markdown Code Block Highlighting
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/guide/writing.mdx
Demonstrates the use of fenced code blocks with language identifiers for syntax highlighting in Markdown. This is essential for presenting code examples clearly.
```markdown
```js
export const title = 'Hello'
```
```
--------------------------------
### Route Path Check Example
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/advanced/theme-guide/special-pages.mdx
Implement logic based on the current route path to conditionally execute code or render specific components. This allows for dynamic behavior based on the accessed URL.
```javascript
const route = ctx.page.routePath
if (route === '/menu') { /* ... */ }
```
--------------------------------
### MDX Blockquote Syntax
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/guide/writing.mdx
Shows how to create blockquotes in MDX using the '>' character. Consecutive lines starting with '>' are merged into a single blockquote, and blank lines create separate blockquotes.
```mdx
> This is a blockquote.
>
> A line containing only `>` represents a blank line within the same block.
> Consecutive quoted lines are merged into a single block.
> A blank line between `>` blocks renders them as separate quotes.
```
--------------------------------
### ToC Data Structure Example (JavaScript)
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/advanced/theme-guide/toc.mdx
Illustrates the structure of each entry in the table of contents (ToC) data provided by Methanol. Each entry includes its depth, a unique ID, the heading text, and any nested children headings.
```javascript
{
ddepth: 2,
id: 'my-heading',
value: 'My heading',
children: []
}
```
--------------------------------
### Branching Patterns Example
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/advanced/theme-guide/special-pages.mdx
Illustrates common strategies for implementing conditional logic in Methylene to handle different page types or content. These patterns help in managing diverse page functionalities within a project.
```javascript
// By file extension
ctx.page.path.endsWith('.html')
// By route
ctx.page.routePath === '/menu'
// By frontmatter
ctx.page.frontmatter?.layout === 'landing'
```
--------------------------------
### Custom PWA Configuration with Vite Plugins
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/guide/offline.mdx
Provides full control over the PWA setup by disabling default Methanol PWA integration (`pwa: false`) and adding custom vite-plugin-pwa configurations directly to the 'vite.plugins' array in methanol.config.js. This is suitable for advanced use cases requiring custom service worker strategies.
```javascript
import customPwaPlugin from 'vite-plugin-pwa';
export default () => ({
pwa: false,
vite: {
plugins: [
customPwaPlugin({
// Custom PWA configuration options here
})
]
}
})
```
--------------------------------
### Build and Preview with Pagefind
Source: https://context7.com/sudomaker/methanol-docs/llms.txt
Commands to build the project with or without the search index, and to preview the site with search functionality enabled.
```bash
# Build with search index
npx methanol build --search
# Build without search
npx methanol build --no-search
# Preview with search functionality
npx methanol serve
```
--------------------------------
### Asset Management with Public and Relative Paths
Source: https://context7.com/sudomaker/methanol-docs/llms.txt
Demonstrates how to link to assets stored in the public directory (served from root) and assets stored relatively within the pages directory.
```mdx
---
title: Asset Examples
---
# Working with Assets
## Public Directory Assets
Files in `public/` are served from root:
[Download PDF](/downloads/document.pdf)
## Relative Assets
Store images alongside pages:
## External Assets
```
--------------------------------
### Define Theme Object
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/advanced/theme-guide/index.mdx
Demonstrates the structure of the theme object typically defined in `theme/index.js`, including paths for various theme assets and configurations.
```javascript
import PageTemplate from './page.jsx'
export default () => ({
theme: {
root: '.',
template: PageTemplate,
componentsDir: './components',
pagesDir: './pages',
publicDir: './public',
sources: {
'/theme': './sources'
}
}
})
```
--------------------------------
### Execute Build with Methanol CLI
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/guide/publishing.mdx
This command initiates an optimized build process for the static site, populating the 'dist/' directory with the generated files. It's a core step before deployment.
```bash
npx methanol build
```
--------------------------------
### Displaying Page Title and Route in MDX
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/advanced/mdx-runtime.mdx
Demonstrates how to access and display the page's title (from frontmatter or context) and the current route path using MDX syntax and the injected `ctx` object.
```mdx
# {frontmatter.title ?? ctx.page.title}
Current Route: {ctx.routePath}
```
--------------------------------
### Directory Structure for Assets
Source: https://context7.com/sudomaker/methanol-docs/llms.txt
Illustrates the project directory structure for managing assets, including files in the public directory and images alongside MDX files.
```directory structure
project/
├── public/
│ ├── logo.png # → /logo.png
│ └── downloads/
│ └── document.pdf # → /downloads/document.pdf
└── pages/
└── guide/
├── setup.mdx
└── architecture-diagram.png # Relative reference
```
--------------------------------
### Methanol CLI Execution via Node
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/reference/cli.mdx
Executes Methanol commands directly using Node.js, pointing to the installed module's binary. This method is useful for specific execution environments or debugging.
```bash
node node_modules/methanol/bin/methanol.js dev
```
--------------------------------
### Methanol CLI Dev with Input Path
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/reference/cli.mdx
Initializes the development server, utilizing only the input directory argument. The output path is not considered in development mode.
```bash
npx methanol dev ./pages
```
--------------------------------
### Methanol CLI Build with Input/Output Paths
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/reference/cli.mdx
Builds the project specifying input and output directories as positional arguments. The order of arguments is significant.
```bash
npx methanol build ./pages ./dist
```
--------------------------------
### Configure Methanol Site Behavior (JavaScript)
Source: https://context7.com/sudomaker/methanol-docs/llms.txt
Defines the main configuration for Methanol, controlling site metadata, directory structures, search functionality, PWA integration, syntax highlighting, build performance, Vite settings, and build hooks. This configuration is typically defined in a `methanol.config.js` file.
```javascript
// methanol.config.js
import { common } from '@wooorm/starry-night'
import sourceMdx from '@wooorm/starry-night/source.mdx'
import Sitemap from 'vite-plugin-sitemap'
export default ({ mode, root, HTMLRenderer }) => ({
// Site metadata
site: {
name: 'My Documentation',
logo: '/logo.png', // or false to disable
favicon: '/favicon.ico', // or false to disable
base: '/docs/', // subpath deployment
repoBase: 'https://github.com/owner/repo/edit/main/pages/'
},
// Directory configuration
pagesDir: 'pages', // default: 'pages' or 'docs'
componentsDir: 'components', // default: 'components'
publicDir: 'public', // default: 'public', false to disable
distDir: 'dist', // default: 'dist'
buildDir: 'build', // default: 'build'
// Search configuration
pagefind: {
enabled: true,
excerptLength: 30,
build: {
outputSubdir: 'pagefind',
verbose: true
}
},
// PWA support
pwa: {
manifest: {
name: 'My Site',
short_name: 'MySite'
},
injectManifest: {
globPatterns: ['**/*.{js,css,html,ico,png,svg}']
}
},
// Syntax highlighting
starryNight: {
grammars: [...common, sourceMdx]
},
// Build performance
jobs: 0, // auto based on page count
gfm: true, // GitHub Flavored Markdown
// Vite configuration
vite: ({ command, mode, root, isPreview }) => ({
server: { port: 5173 },
plugins: [
Sitemap({ hostname: 'https://example.com' })
]
}),
// Build hooks
preBuild: ({ data, site, mode }) => {
data.startedAt = Date.now()
console.log('Building:', site.name)
},
preBundle: ({ pages }) => {
console.log('Pages rendered:', pages.length)
},
postBundle: ({ pages, pagesTree }) => {
console.log('Bundle complete')
},
postBuild: ({ data, pages }) => {
console.log('Duration:', Date.now() - data.startedAt, 'ms')
}
})
```
--------------------------------
### Generating Custom Page List in JSX
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/advanced/mdx-runtime.mdx
Illustrates how to iterate over the `ctx.pages` array (a flat list of all page metadata) using JSX to create a custom list of links for all pages in the project.
```jsx
```
--------------------------------
### Get Adjacent Page Links (JavaScript)
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/advanced/theme-guide/prev-next.mdx
Retrieves previous and next page navigation links using `ctx.getSiblings()`. The links are ordered according to the sidebar display. This function returns an object with `prev` and `next` properties, or an empty object if no siblings are found.
```javascript
const { prev, next } = ctx.getSiblings() || {}
```
--------------------------------
### Get Navigation Siblings with ctx.getSiblings (JSX)
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/advanced/mdx-runtime.mdx
The ctx.getSiblings() function retrieves the previous and next pages in the navigation sequence, considering the active root and visibility. It returns an object with 'prev' and 'next' properties, each containing page details, or null if no siblings exist. This is useful for implementing 'Previous' and 'Next' navigation links.
```jsx
{
(() => {
const siblings = ctx.getSiblings()
if (!siblings) return null
return (
)
})()
}
```
--------------------------------
### Create Reusable JSX Components for Rendering (JSX)
Source: https://context7.com/sudomaker/methanol-docs/llms.txt
Demonstrates creating reusable JSX components with different rendering strategies: server-rendered, client-only interactive, and static fallbacks. These components can be imported and used within MDX files.
```jsx
// components/Callout.jsx - Server-rendered component
export default function Callout({ type = 'info', title }, ...children) {
const styles = {
info: 'background: #e3f2fd; border-left: 4px solid #2196f3;',
warning: 'background: #fff3e0; border-left: 4px solid #ff9800;',
error: 'background: #ffebee; border-left: 4px solid #f44336;'
}
return (
)
}
```
```jsx
// components/Counter.static.jsx - Static fallback for SSR
export default function Counter({ initial = 0 }) {
return (
[ JavaScript required ]
)
}
```
--------------------------------
### Theme Sources Mapping in JavaScript
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/advanced/themes/index.mdx
Illustrates how to configure theme sources, mapping virtual URLs to actual file paths within the theme. This is handled by Methanol's resolver, not Vite aliases.
```js
export default () => ({
heme: {
root: './theme',
sources: {
'/theme': './sources'
}
}
})
```
--------------------------------
### Configure Pagefind Search in methanol.config.js
Source: https://context7.com/sudomaker/methanol-docs/llms.txt
Enabling and configuring Pagefind search within the methanol.config.js file. This can be a simple boolean or a detailed object with specific options.
```javascript
// methanol.config.js
export default () => ({
// Simple enable
pagefind: true,
// Or detailed configuration
pagefind: {
enabled: true,
excerptLength: 30,
build: {
outputSubdir: 'pagefind',
verbose: true
}
}
})
```
--------------------------------
### Toggle Search Indexing via CLI
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/reference/search.mdx
Demonstrates how to toggle search indexing per build using the Methanol CLI. The '--search' flag enables indexing, while '--no-search' disables it.
```bash
npx methanol build --search
```
```bash
npx methanol build --no-search
```
--------------------------------
### Starry Night Syntax Highlighting Configuration (JavaScript)
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/reference/configuration.mdx
Controls syntax highlighting using Starry Night (rehype-starry-night). Can be a boolean or an object for specific options. Per-page Frontmatter settings and CLI flags always take precedence.
```javascript
starryNight: false
// or
starryNight: true
// or detailed configuration
starryNight: {
// options passed to rehype-starry-night
}
```
--------------------------------
### rEFui DOM Renderer Demo - Client-side Interactivity
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/advanced/refui.mdx
Demonstrates client-side interactivity using rEFui's DOM renderer. It showcases reactive signals and event handling to update the UI based on user interaction.
```jsx
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) => (
<>
Hello, rEFui
Double: {$(() => count.value * 2)}
)
}
DOMRenderer.render(document.body, App)
```
--------------------------------
### Pagefind Search Configuration (JavaScript)
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/reference/configuration.mdx
Enables and configures full-text search using Pagefind. Options can be a boolean to enable/disable, or an object for detailed configuration. Properties other than 'enabled' and 'build' are passed directly to Pagefind's initialization.
```javascript
pagefind: false
// or
pagefind: { enabled: true }
// or detailed configuration
pagefind: {
enabled: true,
excerptLength: 30,
build: {
outputSubdir: 'pagefind',
verbose: true
}
}
```
--------------------------------
### Methanol CLI Core Commands
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/reference/cli.mdx
Executes core Methanol CLI commands for development, building, and serving. Recommended to use with `npx` for project-specific versions.
```bash
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
```
--------------------------------
### Per-Page Code Highlighting Configuration (MDX)
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/reference/code-highlighting.mdx
This snippet illustrates how to control syntax highlighting on a per-page basis using frontmatter in an MDX file. Setting `starryNight: true` in the frontmatter overrides global configuration for that specific page.
```mdx
---
starryNight: true
---
```
--------------------------------
### Toggle Code Highlighting via CLI (Bash)
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/reference/code-highlighting.mdx
These commands show how to toggle syntax highlighting directly from the command line during the build process. `--highlight` enables it, while `--no-highlight` disables it.
```bash
npx methanol build --highlight
```
```bash
npx methanol build --no-highlight
```
--------------------------------
### Detailed Pagefind Configuration in Methanol
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/reference/search.mdx
Provides a detailed configuration for Pagefind within the methanol.config.js file, including enabling search, setting excerpt length, and configuring build output. Properties not explicitly handled are passed to the Pagefind client UI initialization.
```javascript
export default () => ({
pagefind: {
enabled: true,
excerptLength: 30,
build: {
outputSubdir: 'pagefind',
verbose: true
}
}
})
```
--------------------------------
### PWA Support Configuration (JavaScript)
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/reference/configuration.mdx
Enables Methanol's integrated Progressive Web App (PWA) support, powered by vite-plugin-pwa. Configuration can be a simple boolean or a detailed object for customizing manifest and service worker options.
```javascript
pwa: true
// or
pwa: false
// or detailed configuration
pwa: {
manifest: {
name: 'My Site',
short_name: 'My Site'
},
injectManifest: {
globPatterns: ['**/*.{js,css,html,ico,png,svg}']
}
}
```
--------------------------------
### Relative Linking in Markdown
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/guide/links.mdx
Shows how to use relative paths for linking when a site is hosted under a subpath. This is recommended to avoid issues with root-absolute links and ensure correct navigation.
```markdown
[Next post](./next-post)
[Back to blog](../blog/)
```
--------------------------------
### Exporting Configuration Function (JavaScript)
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/reference/configuration.mdx
The configuration file must export a default function that receives an execution context and returns a configuration object. The context provides information like build mode, project root, and HTML rendering utilities.
```javascript
export default ({ mode, root, HTMLRenderer }) => ({
// configuration properties
})
```
--------------------------------
### Configure Site Base Path in Methanol
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/guide/publishing.mdx
This JavaScript code snippet demonstrates how to configure the 'site.base' property within the methanol.config file. This setting is crucial when deploying the site to a subpath (e.g., '/docs/'). During development with 'methanol dev', this setting is ignored.
```javascript
export default () => ({
site: {
base: '/docs/'
}
})
```
--------------------------------
### Configure Repository Base URL for Edit Links
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/advanced/themes/default.mdx
Configures the base URL for the 'Edit this page' link in the footer. This allows users to directly edit the source file on a git hosting service. The `repoBase` setting can be overridden per-page using frontmatter's `sourceURL`.
```javascript
// methanol.config.js
export default () => ({
site: {
repoBase: 'https://github.com/OWNER/REPO/edit/main/pages/'
}
})
```
--------------------------------
### Root-Absolute Link Generation (MDX/JSX)
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/guide/links.mdx
Illustrates how to generate root-absolute links within MDX or JSX components by wrapping the path with `ctx.withBase`. This is useful for ensuring correct URL generation, especially in subpath deployments.
```mdx
Read
```
--------------------------------
### Accessing Page Title and Excerpt in MDX
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/advanced/mdx-runtime.mdx
Shows how to access specific frontmatter properties like 'excerpt' and the main page title directly from the `ctx.page` object within an MDX file.
```mdx
{ctx.page.title}
{ctx.page.frontmatter?.excerpt}
```
--------------------------------
### Markdown Paragraph Formatting
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/guide/writing.mdx
Illustrates how to format paragraphs in Markdown, including handling newlines and forced line breaks. Blank lines separate paragraphs, while multiple newlines within a paragraph are typically merged.
```markdown
First paragraph line 1
First paragraph line 2 (typically merges with the previous line)
Second paragraph
This line ends with two spaces
resulting in a line break
```
--------------------------------
### Use Custom Components (MDX)
Source: https://github.com/sudomaker/methanol-docs/blob/main/pages/advanced/components.mdx
Shows how to import and utilize a custom component, 'Callout', within an MDX file. This assumes the 'Callout' component is defined elsewhere (e.g., in the components directory).
```jsx
Keep paragraphs short for scannable docs.
```