https://github.com/NicoZweifel/mdx-butler
Easily bundle and manage typed MDX files.
https://github.com/NicoZweifel/mdx-butler
documentation esbuild mdx mdx-bundler server-side-rendering ssg ssr static-site-generation typescript
Last synced: 5 months ago
JSON representation
Easily bundle and manage typed MDX files.
- Host: GitHub
- URL: https://github.com/NicoZweifel/mdx-butler
- Owner: NicoZweifel
- License: mit
- Created: 2024-02-01T03:40:17.000Z (about 1 year ago)
- Default Branch: dev
- Last Pushed: 2024-03-13T01:06:47.000Z (about 1 year ago)
- Last Synced: 2024-12-09T10:50:56.193Z (5 months ago)
- Topics: documentation, esbuild, mdx, mdx-bundler, server-side-rendering, ssg, ssr, static-site-generation, typescript
- Language: TypeScript
- Homepage: https://mdx-butler.com
- Size: 1000 KB
- Stars: 3
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# mdx-butler
Manage and serve [`MDX`](https://mdxjs.com/) documents with typed Frontmatter in applications, that use Server _Side Rendering_ or _Static Site Generation_.
[](https://mdx-butler.com/)
[](https://www.npmjs.com/package/mdx-butler)
[](https://github.com/NicoZweifel/mdx-butler/actions/workflows/test.yml)
[](https://github.com/NicoZweifel/mdx-butler/actions/workflows/test-docs.yml)
## Why use a Service?
Most web frameworks and build tools offer plugins to handle [`MDX`](https://mdxjs.com/) 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](https://github.com/kentcdodds/mdx-bundler)) aims to offer a performant,
flexible and framework-agnostic abstraction to manage your [`MDX`](https://mdxjs.com/) 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](https://github.com/kentcdodds/mdx-bundler) and [esbuild](https://esbuild.github.io/) for efficient compilation and bundling of [`MDX`](https://mdxjs.com/) 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](https://mdx-butler.com/configuration/next)
- [Remix](https://mdx-butler.com/configuration/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](https://mdx-butler.com/customization/DI) and using `MDXBundlerService` directly.
>
> For more information check out the [Configuration](https://mdx-butler.com/configuration) section!
```ts {1,7-10} showLineNumbers
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.
```ts {1-3,7} showLineNumbers
type Frontmatter = {
title: string;
};
// ...
return docs({
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`
```tsx {1,12} showLineNumbers
import { Component } from "mdx-butler/client";
// ...
const doc = docs.filter((x) => slug === x.path)[0];
if (!doc) return
not found;
return (
{doc.frontmatter.title}
);
```
> [!Tip]
> Start editing `MDX` documents inside `/docs` or the configured [working
> directory](https://mdx-butler.com/configuration)
## 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`](https://vike.dev/) for providing a customizable, versatile web framework.
- [`mdx-bundler`](https://github.com/kentcdodds/mdx-bundler) for providing a blazingly fast [`esbuild`](https://esbuild.github.io/mdx-bundler) based bundler for [`MDX`](https://mdxjs.com/) files.
- [`Contentlayer`](https://contentlayer.dev/) for providing inspiration around the [`MDX`](https://mdxjs.com/) Developer Experience.