How do I bulk-import existing Markdown into VeloCMS?

A lot of writers and developers have a folder of .md files — maybe from a Jekyll, Hugo, or Eleventy site, maybe from Obsidian, maybe from years of personal notes that they finally want to publish. VeloCMS can import them in bulk. Here's the exact process.

What VeloCMS expects from your Markdown files

For a clean import, each .md file should have a YAML front matter block at the top. The minimum viable front matter is just a title. The more fields you provide, the more of the import VeloCMS can automate. Here's the full set of supported fields:

---
title: "Your Post Title"
slug: your-post-slug          # Optional — auto-generated from title if absent
excerpt: "Short summary"       # Optional — first paragraph used if absent
date: 2025-11-01               # Optional — import date used if absent
tags:
  - javascript
  - tutorial
author: "Your Name"            # Optional — falls back to blog author
status: published              # Optional — 'draft' or 'published' (default: draft)
coverImage: ./images/cover.jpg # Optional — relative to the .md file
---

File naming convention

VeloCMS's importer accepts any filename — the slug is taken from the front matter, not the filename. But if your front matter doesn't include a slug, VeloCMS generates one from the filename by stripping the .md extension and converting to kebab-case. So a file named BuildingRestAPI.md becomes the slug building-rest-api. Files with dates in the name (2025-11-01-building-rest-api.md, the Jekyll convention) have the date prefix stripped automatically.

Image folder structure

For images to import correctly, keep them in a folder called images/ or assets/ at the same level as your .md files. VeloCMS's ZIP importer uploads referenced images to your R2 storage bucket and rewrites image paths in the imported posts. If your images are at absolute URLs (https://...) they import without any change — VeloCMS leaves external image URLs as-is.

# Recommended ZIP structure for batch import:
your-posts.zip
├── post-one.md
├── post-two.md
├── post-three.md
└── images/
    ├── hero-post-one.jpg
    ├── diagram-post-two.png
    └── screenshot-post-three.webp

Running the batch import

In VeloCMS admin, go to Admin → Tools → Import → Markdown Batch. Click 'Choose ZIP file' and select your archive. VeloCMS shows a preview table with each post's title, slug, detected date, and status (ready / warning / error). Warnings appear when front matter is missing required fields or image references are broken. Review the table, resolve any warnings, then click 'Import All'. Posts import as drafts unless you set status: published in front matter.

Handling front matter variations

Different static site generators use slightly different front matter field names. VeloCMS's importer handles the most common variations automatically: Jekyll uses date, Hugo uses publishDate or date, Gatsby/MDX often uses date and description. The importer maps these aliases: date → published_at, description or summary → excerpt, tags or categories → tags. Fields that don't map to any known VeloCMS field are stored in the post's custom_meta JSON.

After the import: review and publish

After bulk import, all posts land in Admin → Posts as drafts (or published, if your front matter said so). Sort by import date to see the new batch. Click through a sample of posts to verify formatting, check that images loaded, and confirm slugs look right. For posts you want to go live immediately, select them and use the bulk-publish action in the posts table.

Frequently asked questions

• Can I import .mdx files (MDX with JSX)? No — MDX's JSX components can't run in VeloCMS. Import the .md version and recreate any JSX-powered interactive components as VeloCMS editor blocks.
• What Markdown extensions are supported? Standard CommonMark plus GFM (GitHub Flavoured Markdown) — tables, strikethrough, task lists, and fenced code blocks all work.
• Can I import from Obsidian? Yes — Obsidian Markdown is standard CommonMark. Obsidian's internal links ([[Page Name]]) don't carry over, but regular links, images, and callouts do.
• Will duplicate slugs cause problems? If a post with the same slug already exists, the importer skips it and flags it as a conflict in the import report.
• Can I re-import after editing files locally? Yes — re-importing a ZIP that contains files with the same slugs as existing posts shows them as conflicts. You can choose 'overwrite' or 'skip' per post.