Migrate from Markdown
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/contentOptions 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 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 languagemdx, with a warning. - A
README.mdat 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 ./contentThe 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
bodyrich text field that is not localized goes in the file body; other rich text fields become Markdown strings in the front matter.