nicozweifel/mdx-butler

Easily bundle and manage typed MDX files.

mdx-butler

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

Why use a Service?

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.

Setup

Installation

pnpm i mdx-butler mdx-bundler esbuild

Framework Guides

• Next.js
• Remix

Bundling

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

Warning

Exports like docs, MDXBundlerService or any others from the mdx-butler root entrypoint should only be imported in a server or build context.

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

Note

If you require more control, consider injecting dependencies and using MDXBundlerService directly.

For more information check out the Configuration section!

import { docs } from "mdx-butler";

// ...

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

Tip

Automatically generates a FrontmatterProcessor, according to the given fields.

Types

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

type Frontmatter = {
  title: string;
};

// ...

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

Note

The given Fields cannot be undefined after the Frontmatter has been processed.

If a required field is undefined, an Error will be thrown.

Component

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>
);

Tip

Start editing MDX documents inside /docs or the configured working directory

Security Notice

Caution

MDX is javascript. If not carefully done, evaluating user content can expose to XSS attacks.

Always be careful if you are not evaluating your own content.

Mentions

• 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.