MDX Integration

The @ecopages/mdx package enables seamless integration of MDX (Markdown with JSX) into your Ecopages project, allowing you to write content-rich pages with ease.

Installation

To install the MDX integration plugin, run the following command in your project directory:

bunx jsr add @ecopages/mdx

Usage

To incorporate the MDX integration into your Ecopages project, follow these steps:

1. Import the mdxPlugin in your Ecopages configuration file:

import { ConfigBuilder } from '@ecopages/core';
import { mdxPlugin } from '@ecopages/mdx';
import { kitajsPlugin } from '@ecopages/kitajs';

const config = await new ConfigBuilder()
    .setRootDir(import.meta.dir)
    .setBaseUrl(import.meta.env.ECOPAGES_BASE_URL)
    .setIntegrations([mdxPlugin(), kitajsPlugin()])
    .build();

export default config;

Creating MDX Pages

Once the MDX integration is set up, you can create pages using MDX syntax. Here's a simple example:

import { Card } from '@/components/card';
import { BaseLayout } from '@/layouts/base-layout';

export const config = {
    dependencies: {
      importMeta: import.meta,
      components: [Card, BaseLayout],
    }
};

<BaseLayout class="prose">

# MDX Page

This is a test page.

<Card title="Hello" copy="This is the card copy" />

</BaseLayout>

Key Features

1. Markdown Syntax: Write content using familiar Markdown syntax.
2. JSX Integration: Seamlessly integrate JSX components within your Markdown.
3. Code Highlighting: Automatic syntax highlighting for code blocks.
4. Frontmatter Support: Define metadata using YAML frontmatter.

Best Practices

1. Component Imports: Import and use custom components at the top of your MDX files.
2. Layouts: Use layouts to maintain consistent page structures across your MDX content.
3. Metadata: Utilize frontmatter for defining page-specific metadata.

Integration with Other Plugins

The MDX integration works well with other Ecopages plugins. For example, you can use it alongside the Lit plugin:

import { ConfigBuilder } from '@ecopages/core';
import { mdxPlugin } from '@ecopages/mdx';
import { litPlugin } from '@ecopages/lit';

const config = await new ConfigBuilder()
    .setRootDir(import.meta.dir)
    .setBaseUrl(import.meta.env.ECOPAGES_BASE_URL)
    .setIntegrations([mdxPlugin(), litPlugin()])
    .build();

export default config;

Note: Currently, when using the Lit plugin with MDX, Lit components are not server-side rendered within MDX files. Instead, they are loaded and rendered on the client side.

By leveraging the MDX integration, you can create rich, interactive content pages that combine the simplicity of Markdown with the power of components in your Ecopages project.