Importing Markdown

Have a pile of writing from another tool — plain .md files (a static-site export, a previous CMS, or a notes folder)? The Import Markdown screen turns them into draft pages or posts in one batch: upload, review, publish. Nothing is auto-published — every imported file lands as an ordinary draft, exactly as if you’d typed it.

Starting an import

1. In the admin, head to a Pages or Posts list, then open Import Markdown (pages and posts each have their own route; type sets the target).
2. Set the default language for the batch.
3. Select up to 100 .md/.markdown files at once (whole batch up to 40 MiB).
4. Upload.

If the optional conversion modules aren’t installed on your server, the form tells you before you choose a single file, and the import fails with “ask an admin to install them” — it never fails silently mid-batch.

Front matter

Each file can begin with an optional --- YAML header block:

---
title: My First Post
slug: my-first-post
language: en
category: News
tags: [announcements, tips]
date: 2024-03-14
meta_title: My First Post — Example Site
meta_description: A short searchable summary…
---

Fallback rules make front matter optional:

• Title: front-matter title → the document’s first # heading (removed from the body so it doesn’t appear twice) → the filename.
• Slug: front-matter slug → a clean version of the title → the cleaned filename — with automatic dupes (-2, -3…) if two files would land on the same address.
• Tags: a comma string or a YAML list both work.

Rules that apply when you do include a header:

• Keep it flat — the keys above only. A nested list under title: is rejected with the field named.
• language: must be a language your site actually has configured, and one your account is allowed to write — checked per file.
• A date:/published_at: value is accepted in plain YYYY-MM-DD or with a time; a real calendar check rejects month 13, day 45, etc. A nonsense date doesn’t fail the file — it’s just ignored.
• No scheduling: front-matter dates are recorded as the item’s metadata only — publishing stays a manual/review decision. This is explicit in the code (“auto-scheduling ruled out”), so nothing goes live unexpectedly.

What you get back

• All files become drafts: nothing is published by an import, ever.
• Body markdown converts to the same HTML your editor writes — including converting a leftover # heading one level down to an H2, since the editor’s heading structure starts at H2.
• A site rebuild happens automatically if at least one draft was created (these drafts exist in the CMS straight away; only their publication waits for you).
• The results screen is per-file: each created draft with its edit link and the file it came from, and each failure with its precise error.

Which failures you might see

Every problem is reported by filename, in plain language:

Per-file failures never take the batch down: valid files keep importing while invalid ones report.

Good practice

• Bring your images separately: image URLs in the body are imported verbatim — the practical move is to upload images to the media library first and reference them from the Markdown, so drafts already point at working URLs before you go live.
• Let titles do the slugs — if two batch files would collide, the importer suffixes for you; overriding slugs is done with front-matter slug: only where it matters.
• Format painless: accept the H1-fallback title only as the last resort; writing title: in front matter keeps starting pages clean.
• Verify columns and drafts one at a time — the results screen links each draft immediately after import for review pass.

The short version

A folder of Markdown becomes a folder of drafts in one request: optional YAML defines title, slug, category/tags, language, and metadata; everything else derives; nothing is published automatically; the per-file result screen is your checklist for what needs a look before going live.