docs menu

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/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 for the shared flags, the report and re-runs.

OptionWhat it is
dir, pathThe folder to read
filesThe files inline, as [{ path, content }] (the only form the tool accepts)
mediaDirWhere local images live. Default: a public/ or static/ folder next to it
languagesLanguage codes, the default first. Default: from a galerne.config.json in the folder, else en first

How content maps#

MarkdownGalerne
FolderDocument type, singular of the folder name (posts/ gives post); files at the root are page
Path under the folderDocument id; index and _index files are handled
Front matterFields, typed from their values; values that all name documents of a folder become references
BodyA body rich text field; local links become doc:<id>, local images media:<id>
Local file paths in front matterMedia
Language folder (fr/…) or suffix (x.fr.md)Document-level translations, .<lang> added to the id
draft: true, published: falseA draft
No slug in the front matterA 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.