---
title: Convert
description: MDX-to-markdown conversion APIs from leadtype/convert.
group: reference
lastModified: '2026-05-11T20:02:32-07:00'
lastAuthor: 'github-actions[bot]'
---
# Convert

The `leadtype/convert` entry point flattens MDX into clean markdown via the [remark plugin stack](/docs/reference/remark).

```ts
import {
  convertAllMdx,
  convertMdxToMarkdown,
  writeMdxFileAsMarkdown,
} from "leadtype/convert";
```

The CLI ([`leadtype generate`](/docs/reference/cli)) calls `convertAllMdx` internally — use these APIs directly when you need custom plugin order, in-memory output, or per-file control.

## convertAllMdx

Batch convert a docs tree:

```ts
import { defaultRemarkPlugins, remarkInclude } from "leadtype/remark";

await convertAllMdx({
  srcDir: "docs",
  outDir: "public/docs",
  remarkPlugins: [remarkInclude, ...defaultRemarkPlugins],
  enrichFrontmatterFromGit: true,
});
```

|Option|Description|
|--|--|
|`srcDir`|Root directory of `.mdx` files.|
|`outDir`|Destination for `.md` output. The directory structure mirrors `srcDir`.|
|`remarkPlugins`|Plugin array. Usually `[remarkInclude?, ...defaultRemarkPlugins]`. Order matters.|
|`enrichFrontmatterFromGit`|When true, adds `lastModified` and `lastAuthor` from git history.|

The function is concurrent — large trees process in parallel.

## convertMdxToMarkdown

Convert one file in memory and get back the markdown plus parsed frontmatter:

```ts
const result = await convertMdxToMarkdown(
  "docs/quickstart.mdx",
  defaultRemarkPlugins,
  /* enrichFrontmatterFromGit */ false,
);

console.log(result.markdown);
console.log(result.frontmatter);
```

Use this when you want to render the output yourself, validate it before writing, or feed it to another pipeline stage without touching disk.

## writeMdxFileAsMarkdown

Convert one file and write the output:

```ts
await writeMdxFileAsMarkdown({
  srcPath: "docs/quickstart.mdx",
  outPath: "public/docs/quickstart.md",
  remarkPlugins: defaultRemarkPlugins,
});
```

## Behavior notes

* **Frontmatter is preserved.** YAML blocks at the top of the source `.mdx` survive into the output `.md`.
* **Synthesized frontmatter.** A page without frontmatter gets `title` (and sometimes `description`) inferred from the rendered markdown.
* **Tables and Mermaid blocks are compacted** after rendering so agent output stays clean.
* **Conversion is concurrent** — there is no global state.

## Pairing with remark plugins

In most setups, pair `convertAllMdx` with the default plugin stack and `remarkInclude` if your docs use partials:

```ts
import { defaultRemarkPlugins, remarkInclude } from "leadtype/remark";

remarkPlugins: [remarkInclude, ...defaultRemarkPlugins];
```

Place `remarkInclude` *before* the defaults so includes expand into the source AST before component flattening sees them. See [Remark plugins](/docs/reference/remark) for the full stack and order rationale.

The include plugin supports tags such as `<include src="./shared/auth.mdx" />` and section reuse with `<include src="./shared/auth.mdx#session-flow" />`. Section reuse expects a lowercase `<section id="session-flow">` block in the included file.