{"id":22964566,"url":"https://github.com/NicoZweifel/mdx-butler","last_synced_at":"2025-08-13T08:31:53.695Z","repository":{"id":220285446,"uuid":"751162232","full_name":"NicoZweifel/mdx-butler","owner":"NicoZweifel","description":"Easily bundle and manage typed MDX files.","archived":false,"fork":false,"pushed_at":"2024-03-13T01:06:47.000Z","size":1026,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"dev","last_synced_at":"2024-12-09T10:50:56.193Z","etag":null,"topics":["documentation","esbuild","mdx","mdx-bundler","server-side-rendering","ssg","ssr","static-site-generation","typescript"],"latest_commit_sha":null,"homepage":"https://mdx-butler.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NicoZweifel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-02-01T03:40:17.000Z","updated_at":"2024-03-07T01:58:43.000Z","dependencies_parsed_at":"2024-02-01T09:24:10.309Z","dependency_job_id":"2a163f4f-33dd-4083-8360-5fd3511e31bf","html_url":"https://github.com/NicoZweifel/mdx-butler","commit_stats":{"total_commits":259,"total_committers":1,"mean_commits":259.0,"dds":0.0,"last_synced_commit":"ad332e203843a263c2c6b2138fa4cdf8e956e5be"},"previous_names":["nicozweifel/mdx-tug"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NicoZweifel%2Fmdx-butler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NicoZweifel%2Fmdx-butler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NicoZweifel%2Fmdx-butler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NicoZweifel%2Fmdx-butler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NicoZweifel","download_url":"https://codeload.github.com/NicoZweifel/mdx-butler/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":229749313,"owners_count":18118325,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["documentation","esbuild","mdx","mdx-bundler","server-side-rendering","ssg","ssr","static-site-generation","typescript"],"created_at":"2024-12-14T20:11:14.660Z","updated_at":"2025-08-13T08:31:53.683Z","avatar_url":"https://github.com/NicoZweifel.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mdx-butler\n\nManage and serve [`MDX`](https://mdxjs.com/) documents with typed Frontmatter in applications, that use Server _Side Rendering_ or _Static Site Generation_.\n\n\n[![npm](https://img.shields.io/badge/npm-v0.5.6-red)](https://www.npmjs.com/package/mdx-butler)\n[![test](https://github.com/NicoZweifel/mdx-butler/actions/workflows/test.yml/badge.svg)](https://github.com/NicoZweifel/mdx-butler/actions/workflows/test.yml)\n[![test-docs](https://github.com/NicoZweifel/mdx-butler/actions/workflows/test-docs.yml/badge.svg)](https://github.com/NicoZweifel/mdx-butler/actions/workflows/test-docs.yml)\n\n![logo](/docs/public/butler.png)\n\n## Why use a Service?\n\nMost web frameworks and build tools offer plugins to handle [`MDX`](https://mdxjs.com/) documents.\nWhile convenient, these plugins can in some cases limit control, force specific dependencies,\ncreate performance bottlenecks and complicate the migration of your documentation to a Microservice, CMS or database in the future.\n\n**mdx-butler** (built upon [mdx-bundler](https://github.com/kentcdodds/mdx-bundler)) aims to offer a performant,\nflexible and framework-agnostic abstraction to manage your [`MDX`](https://mdxjs.com/) documents.\nThis maximizes flexibility and future-proofs your work for easy updates, migrations, and changes to your content source.\n\n- **Enhanced content organization** with **typed Frontmatter** and **MDX syntax** support for titles and descriptions within frontmatter.\n- **Framework independent:** Work smoothly without worrying about framework-specific plugins and dependencies.\n- **Adaptability:** Switch content sources (Backend/Service, CMS, database, etc.) without major rewrites.\n- **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.\n- **Customization:** Easily inject globals, components, and application logic for rich, interactive documentation.\n\n## Setup\n\n### Installation\n\n```\npnpm i mdx-butler mdx-bundler esbuild\n```\n\n### Framework Guides\n\n- [Next.js](https://mdx-butler.com/configuration/next)\n- [Remix](https://mdx-butler.com/configuration/remix)\n\n### Bundling\n\nThe easiest way to get all bundled documents within a folder is to call the `docs` function.\n\n\u003e [!Warning]\n\u003e Exports like `docs`, `MDXBundlerService` or any others from the `mdx-butler` root entrypoint\n\u003e should only be imported in a server or build context.\n\nOptions and dependencies can be passed to `docs` or `MDXBundlerService.create`.\n\n\u003e [!Note]\n\u003e If you require more control, consider [injecting\n\u003e dependencies](https://mdx-butler.com/customization/DI) and using `MDXBundlerService` directly.\n\u003e\n\u003e For more information check out the [Configuration](https://mdx-butler.com/configuration) section!\n\n```ts {1,7-10} showLineNumbers\nimport { docs } from \"mdx-butler\";\n\n// ...\n\nreturn docs({\n  fields: {\n    title: {\n      required: true,\n    },\n  },\n});\n```\n\n\u003e [!Tip]\n\u003e Automatically generates a `FrontmatterProcessor`, according to the given\n\u003e `fields`.\n\n#### Types\n\nTo guarantee a correct type inference, specifying the `Frontmatter` type is recommended.\n\n```ts {1-3,7} showLineNumbers\ntype Frontmatter = {\n  title: string;\n};\n\n// ...\n\nreturn docs\u003cFrontmatter\u003e({\n  fields: {\n    title: {\n      required: true,\n    },\n  },\n});\n```\n\n\u003e [!Note]\n\u003e The given Fields cannot be undefined after the `Frontmatter` has been processed.\n\u003e\n\u003e If a required field is `undefined`, an `Error` will be thrown.\n\n### `Component`\n\n```tsx {1,12} showLineNumbers\nimport { Component } from \"mdx-butler/client\";\n\n// ...\n\nconst doc = docs.filter((x) =\u003e slug === x.path)[0];\n\nif (!doc) return \u003cdiv\u003enot found\u003c/div\u003e;\n\nreturn (\n  \u003cdiv\u003e\n    \u003ch1\u003e{doc.frontmatter.title}\u003c/h1\u003e\n    \u003cComponent doc={doc} /\u003e\n  \u003c/div\u003e\n);\n```\n\n\u003e [!Tip]\n\u003e Start editing `MDX` documents inside `/docs` or the configured [working\n\u003e directory](https://mdx-butler.com/configuration)\n\n## Security Notice\n\n\u003e [!CAUTION]\n\u003e MDX is javascript. If not carefully done, evaluating user content can expose to XSS attacks.\n\u003e\n\u003e Always be careful if you are not evaluating your own content.\n\n## Mentions\n\n- [`vike`](https://vike.dev/) for providing a customizable, versatile web framework.\n- [`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.\n- [`Contentlayer`](https://contentlayer.dev/) for providing inspiration around the [`MDX`](https://mdxjs.com/) Developer Experience.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNicoZweifel%2Fmdx-butler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FNicoZweifel%2Fmdx-butler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNicoZweifel%2Fmdx-butler/lists"}