# gt: General Translation CLI tool: MDX and Markdown
URL: https://generaltranslation.com/en-US/docs/cli/reference/formats/mdx-md-files.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Translate MDX and Markdown files with the General Translation CLI. API reference for the MDX and Markdown file formats.

The CLI translates MDX (`mdx`) and Markdown (`md`) files. All syntax and formatting in the source files is preserved in the translated files.

## Overview [#overview]

| Topic | Description |
| --- | --- |
| [Configuration](#config) | Select source files and translated output paths. |
| [Custom heading IDs](#heading-ids) | Preserve explicit heading anchors. |
| [Static data exports](#data-exports) | Reuse unchanged strings in eligible exports. |
| [Translated file names](#transform) | Remap output file names with `transform`. |
| [Links and assets](#localize) | Localize URLs, imports, and relative assets. |

## Configuration [#config]

Add an `mdx` or `md` entry under `files` with an `include` array of glob patterns. Use the `[locale]` placeholder so the CLI can find source files and save translations to the right path.

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["ja"],
  "files": {
    "mdx": {
      "include": ["content/docs/[locale]/**/*.mdx"],
      "transform": "*.[locale].mdx"
    }
  }
}
```

This translates every MDX file under `content/docs/en` and saves the results to `content/docs/ja`. Use the `md` key instead for Markdown files. See the [configuration reference](/docs/cli/reference/config#files) for all file keys.

## Custom heading IDs [#heading-ids]

Mintlify-style `{#id}` suffixes remain attached to their headings after translation:

```markdown
## Configure the client {#configure-client}
```

Explicit heading IDs require `gt` 2.17.3 or later.

When `experimentalAddHeaderAnchorIds` is set to `'mintlify'`, the CLI writes Mintlify-native `{#id}` syntax on every translated heading and reuses the source heading's ID. Headings nested in JSX are moved to the margin when needed because Mintlify recognizes the suffix only on headings with up to three leading spaces. This mode requires `gt` 2.20.4 or later.

## Update static data exports [#data-exports]

When an updated MDX file contains static data exports, General Translation reuses matching strings from earlier translations and translates only new or changed strings. Reuse applies when every exported variable in the chunk contains only static string, number, bigint, boolean, or `null` literals, arrays, and plain objects. TypeScript assertion wrappers are supported.

Exports with spreads, identifiers, function calls, template literals, JSX, or computed object keys use the standard translation path. Running [`gt translate --force`](/docs/cli/reference/commands/translate) or applying Glossary translations also skips incremental reuse.

## Rename translated files [#transform]

The `transform` key remaps output file names. In the example above, `*.[locale].mdx` changes the translated extension to `.ja.mdx`. Use this when your docs framework expects a locale in the file name rather than in the directory path.

## Localize links and assets [#localize]

Several experimental [`gt translate`](/docs/cli/reference/commands/translate#experimental) flags apply specifically to `md` and `mdx` output:

- `--experimental-localize-static-urls` — localizes URLs in translated files.
- `--experimental-localize-static-imports` — localizes static imports in translated files.
- `--experimental-localize-relative-assets` — rewrites relative image asset URLs in translated files.
- `--experimental-hide-default-locale` — hides the default locale from localized paths.

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.