Manage and serve MDX documents with typed Frontmatter in applications, that use Server Side Rendering or Static Site Generation.

Most web frameworks and build tools offer plugins to handle MDX documents. While convenient, these plugins can in some cases limit control, force specific dependencies, create performance bottlenecks and complicate the migration of your documentation to a Microservice, CMS or database in the future.

mdx-butler (built upon mdx-bundler) aims to offer a performant, flexible and framework-agnostic abstraction to manage your MDX documents. This maximizes flexibility and future-proofs your work for easy updates, migrations, and changes to your content source.

• Enhanced content organization with typed Frontmatter and MDX syntax support for titles and descriptions within frontmatter.
• Framework independent: Work smoothly without worrying about framework-specific plugins and dependencies.
• Adaptability: Switch content sources (Backend/Service, CMS, database, etc.) without major rewrites.
• Performance: Leverages mdx-bundler and esbuild for efficient compilation and bundling of MDX documents with imported dependencies.
• Customization: Easily inject globals, components, and application logic for rich, interactive documentation.

pnpm i mdx-butler mdx-bundler esbuild

• Next.js
• Remix

The easiest way to get all bundled documents within a folder is to call the docs function.

Options and dependencies can be passed to docs or MDXBundlerService.create.

import { docs } from "mdx-butler";

// ...

return docs({
  fields: {
    title: {
      required: true,
    },
  },
});

To guarantee a correct type inference, specifying the Frontmatter type is recommended.

type Frontmatter = {
  title: string;
};

// ...

return docs<Frontmatter>({
  fields: {
    title: {
      required: true,
    },
  },
});

import { Component } from "mdx-butler/client";

// ...

const doc = docs.filter((x) => slug === x.path)[0];

if (!doc) return <div>not found</div>;

return (
  <div>
    <h1>{doc.frontmatter.title}</h1>
    <Component doc={doc} />
  </div>
);

• vike for providing a customizable, versatile web framework.
• mdx-bundler for providing a blazingly fast esbuild based bundler for MDX files.
• Contentlayer for providing inspiration around the MDX Developer Experience.