MDX Integration

The @ecopages/mdx package brings the power of MDX (Markdown with JSX) to Ecopages. It allows you to write content-rich pages using Markdown syntax while seamlessly embedding interactive components.

Installation

bunx jsr add @ecopages/mdx

Usage

To start using MDX, add the mdxPlugin to your Ecopages configuration.

import { ConfigBuilder } from '@ecopages/core';
import { mdxPlugin } from '@ecopages/mdx';
 
const config = await new ConfigBuilder()
	.setRootDir(import.meta.dir)
	.setBaseUrl(import.meta.env.ECOPAGES_BASE_URL)
	.setIntegrations([mdxPlugin()])
	.build();
 
export default config;

Implicit React Support

By default, the MDX plugin is configured to use React as the JSX runtime. This means you do not need to manually configure React support or import React in every MDX file. The plugin handles the necessary imports and environment setup for you.

Features

Layouts

You can define a wrapper layout for your MDX content by exporting a layout component from your MDX file. This is useful for wrapping your content in a consistent page structure.

import { BaseLayout } from '@/layouts/base-layout';
 
export const config = {
  layout: BaseLayout,
};
 
# Hello World
 
This content will be wrapped by the BaseLayout component.

Metadata

Page metadata (like title and description) can be defined by exporting a getMetadata function.

export const getMetadata = () => ({
  title: 'My MDX Page',
  description: 'This is a description for the MDX page.'
});
 
# Content
 
Page content goes here...

Using Components

You can import and use components directly in your MDX files. Remember to export a config object if your components have dependencies that need to be resolved.

import { Card } from '@/components/card';
import { BaseLayout } from '@/layouts/base-layout';
 
export const config = {
  layout: BaseLayout,
  dependencies: {
    components: [Card, BaseLayout],
  },
};
 
# Dashboard
 
<Card title="Analytics" value="100%" />
<Card title="Users" value="500" />

Configuration

The mdxPlugin accepts standard MDX compile options.

mdxPlugin({
  compilerOptions: {
    remarkPlugins: [],
    rehypePlugins: [],
    // You can also change the JSX runtime if needed (default: 'react')
    jsxImportSource: 'react', 
  }
})

Using MDX with React Router

If you are using @ecopages/react with a client-side router (e.g., @ecopages/react-router), enable MDX directly within the React plugin instead of using this standalone plugin:

import { reactPlugin } from '@ecopages/react';
import { ecoRouter } from '@ecopages/react-router';
 
reactPlugin({
  router: ecoRouter(),
  mdx: { enabled: true },
})

This ensures unified routing, hydration, and HMR for both .tsx and .mdx pages. See the React Integration for details.

Integration with Other Frameworks

While React is the default, MDX can be used with other frameworks like Lit, though it may require specific configuration or client-side rendering considerations.

For example, using Lit components:

import { litPlugin } from '@ecopages/lit';
 
// ... inside config
.setIntegrations([mdxPlugin(), litPlugin()])

In your MDX file, standard Lit components will work as custom elements (once registered via their import).