# Migrate from Markdown

> Import a folder of Markdown or MDX files with front matter into Galerne, and export Galerne content as Markdown files: folder layout, languages, drafts, media and losses.

The Markdown source reads a folder of `.md`, `.mdx` and `.markdown` files with YAML or TOML front matter, as used by Astro, Hugo, Eleventy, Jekyll or Next.js sites.

## Import

```bash
galerne import --from markdown --dir ./src/content --dry-run
galerne import --from markdown --dir ./src/content
```

Options go after `--from` as flags in kebab case (`projectId` is `--project-id`). With the `import_from` tool, they go in `options`. See the [migration overview](/docs/migrate.md) for the shared flags, the report and re-runs.

| Option | What it is |
|---|---|
| `dir`, `path` | The folder to read |
| `files` | The files inline, as `[{ path, content }]` (the only form the tool accepts) |
| `mediaDir` | Where local images live. Default: a `public/` or `static/` folder next to it |
| `languages` | Language codes, the default first. Default: from a `galerne.config.json` in the folder, else `en` first |

## How content maps

| Markdown | Galerne |
|---|---|
| Folder | Document type, singular of the folder name (`posts/` gives `post`); files at the root are `page` |
| Path under the folder | Document id; `index` and `_index` files are handled |
| Front matter | Fields, typed from their values; values that all name documents of a folder become references |
| Body | A `body` rich text field; local links become `doc:<id>`, local images `media:<id>` |
| Local file paths in front matter | Media |
| Language folder (`fr/…`) or suffix (`x.fr.md`) | Document-level translations, `.<lang>` added to the id |
| `draft: true`, `published: false` | A draft |
| No slug in the front matter | A slug from the file name |

## What the import loses

The report lists each of these when it happens.

- In MDX, import and export statements are dropped. A component whose props are strings, numbers or JSON and whose children are plain text becomes an embed of a block type named after it, with its text in `children`. Other components become code blocks with language `mdx`, with a warning.
- A `README.md` at the root is skipped.
- Without `languages`, only common language codes are recognised in folder names and suffixes.

## Export to Markdown

```bash
galerne export --to markdown --out ./content
```

The folder holds One file per document under a folder per type (`posts/<id>.md`, pages at the root), translations as `<id>.<lang>.md`, media in `media/`, `galerne.config.json` and a `README.md`.

The export loses:

- The draft is written when a newer draft exists, with a warning; unpublished documents get `draft: true`.
- Image alt text, caption, hotspot and crop are dropped, and so is underline.
- Only a `body` rich text field that is not localized goes in the file body; other rich text fields become Markdown strings in the front matter.
