MDX

Readma can compile MDX sources into the readme sections of workspace members. MDX gives you JSX components inside markdown — handy for structured content like comparison tables or lists generated from data.

note

Only workspace member sections can be overridden with MDX. The root readme is fully driven by readma.config.ts.

How to

1. Add a readma/sections folder inside the member:

   packages/core/
   └── readma/
       └── sections/
           └── usage.mdx

2. Write the section content in usage.mdx (the file name is the section key):

   ## Basic usage
   
   Import the renderer and feed it your template args:
   
   import { readme } from "@readma/core";
   
   const markdown = await readme(args);

3. Rerun gen — the member readme now embeds the compiled MDX.

deno run -A jsr:@readma/cli gen

Precedence

For each section key, the first match wins:

1. readma/sections/<key>.mdx in the member folder (compiled),
2. sections.<key> from readma.config.ts,
3. the automatic installation snippet (only for that key).

Empty or broken MDX files are skipped with a warning and the config value is used instead — a half-written MDX file never breaks a generation.

Which keys can be overridden

Any key: builtin section keys (features, usage, roadmap…) as well as your custom section keys. The section heading itself (title, emoji, position) still comes from the section pipeline, so MDX only replaces the body.