How to import Markdown files into your blog or help center

In TeleportHQ, you bring a whole folder of Markdown articles into your Help Center or Blog at once: zip the folder, click the Import button (the upload arrow) at the top of the panel, and drop the ZIP. Folders become categories, each file's front matter sets its title, date, order and more, pictures next to the files are uploaded and placed, and links between files become links between articles. You see a plan of what will happen before anything is written. Importing the same folder again updates the articles in place.

Before you start#

• Your project needs the Help Center or the Blog switched on. See How to add a help center to your site or How to add a blog to your site.
• A single .md file can be up to 10 MB and becomes one article; pictures it refers to by path are left out, pictures it links by web address stay as links. A .zip can be up to 250 MB; each picture inside it follows your plan's file size limit. See Which files can I upload, and how big can they be?
• For CSV and JSON files, see How to import or export blog posts.
• Want your AI to write the files? See How to build your help center from your codebase with ChatGPT or Claude: it holds a prompt that has your AI tool produce a ZIP in this format.

1. Prepare your files#

One file is one article#

Every .md file is one article. Nothing in it is required:

• The title comes from title, else from the file's first # heading (which is then not repeated in the text), else from the file name.
• The address comes from slug, else from the file name: change-your-order.md becomes /help/change-your-order (or /blog/…). A slug with slashes keeps its last part.
• A number at the start of a file or folder name, as in 02-plans.md, sets its order and is left out of the title and the address.
• The excerpt comes from description, else from the first paragraph.

Front matter#

Front matter is a block between two --- lines at the top of the file:

---
title: How do I change my order?
description: Change the day, the items or the address of an order until the day before delivery.
date: 2026-03-15
last_verified: 2026-10-01
order: 2
author: Ana
tags: [orders, delivery]
related: [cancel-an-order]
redirect_from: [/old-help/change-order]
---

TeleportHQ reads these names. The other spellings in brackets work too:

Folders become categories#

• Folders become categories, nested the way they are: orders/delivery/ is Delivery under Orders.
• A _category.md file inside a folder sets the category's name (title, label), description (else its first paragraph) and order (position, weight, sidebar_position; its place among its sibling categories), and can carry redirect_from for the category's old addresses. Without one, the folder's name is used. On a later import, a category you already have keeps its order and its description (an empty description is filled in); a renamed category is a new one.
• README.md, index.md, folders whose names start with _ or ., and files that aren't Markdown or pictures are left out. A single folder that holds everything is ignored, so you can zip the folder itself.

Pictures#

• Put pictures next to the articles and refer to them by path: ![The order page](pictures/change-order-1.png). Each is uploaded to your files once (to the help-center or blog folder of your Public files) and placed in the article; a picture already in your files (same name and size) is reused. Pictures linked by web address stay as links. A picture in a format TeleportHQ can't upload (.avif, .heic, .heif, .bmp, .tif, .tiff) is left out and listed in the plan and the result: convert it to .png, .jpg or .webp first.
• To place a picture beside the text, give it a title: ![The order page](pictures/change-order-1.png "left 30") floats it on the left at 30% of the column. right and center work the same way, like the picture's Left / Center / Right buttons in the editor. Text runs beside a picture up to 50% wide.
• Add own-row to keep it on its side with the text below it: "left 30 own-row".

Links and the rest of the text#

• A link to another file's path, such as ../orders/cancel-an-order.md#refunds, becomes a link to that article's address on your site, with the #refunds part kept, even if that file isn't in the ZIP yet. Until it's imported, the editor's Issues window lists the link as broken. See How to find and fix broken links on your site.
• Headings, lists, tables with their header row, code blocks with their language, pictures and links are kept. > **Note:** … or > [!NOTE] becomes a callout: note, tip, important, warning or caution.

2. Import the ZIP#

1. In the left sidebar (the icon column), click Help Center, or Blog.

2. At the top right of the panel, click the upload arrow (tooltip Import Articles, or Import Posts). An empty list also offers Import articles below Create Article.

   

3. Optional: click Format requirements & examples, then Markdown or ZIP of Markdown, to read the format guide in the editor. The copy button copies the example.

   

   

4. Drop the .zip on the box ("Drop a .csv, .json, .md or .zip of Markdown files here"), or click the box to choose it. "Reading the file…" shows while TeleportHQ reads it.

5. Read the plan. Nothing is written yet. It says, for example:

   • "12 articles: 9 new, 3 update articles with the same address";
   • "4 categories from the folders";
   • "18 pictures to upload to your files", "2 pictures already in your files, reused";
   • "3 old addresses to lead to their new pages, with permanent redirects";
   • as warnings, what's missing: "1 picture reference with no file in the ZIP, left out", "2 links to nothing in the ZIP, kept as written";
   • "1 file left out (README, index and non-Markdown files)".

   A box headed with a number of problems (for example "1 problem") lists files that won't be imported, and a box of notes (for example "3 notes") lists, file by file, what TeleportHQ will leave out or change.

6. Leave Publish imported articles on to put the articles live, or turn it off to save them as drafts. A file that says draft or published keeps its own.
7. Click Import followed by the number, for example Import 12 articles. The bar shows Creating categories, Uploading pictures, then Writing articles.

When it's done, a message sums it up, for example "Import finished: 9 articles added, 3 updated, 4 categories created, 18 pictures in your files, 3 old addresses redirected". If there is nothing more to tell, the panel closes. Otherwise it stays open with the notes, such as pictures it couldn't upload or category addresses it couldn't redirect: read them and click Done.

Import again to update#

Import the same folder again after you change it. Articles are matched by their address: new ones are added, changed ones are updated, and the rest stay as they are. The same ZIP twice changes nothing ("3 unchanged").

When an article is updated, its title, text, excerpt, main picture, categories, tags, SEO title and description come from the file again, so changes you made to those in TeleportHQ are replaced. Its author, place in its category, related articles, status and dates change only when the file sets them (the last-updated date is set at every update), so what you set by hand stays. Its address never changes. Articles that aren't in the ZIP are never deleted.

Old addresses become permanent redirects#

When you move a help center to TeleportHQ, keep its old links working: list them under redirect_from in each article, or in a folder's _category.md for a category.

• Each old address becomes a permanent redirect (301) to the article's new page. You find them in Project settings (cog, bottom left) → SEO & social → Search engines → Custom Redirects, where you can read and change them.
• A * stands for any characters: /en/article/*-x1y2z3 takes every old address ending in -x1y2z3.
• Importing again keeps the redirects up to date.
• Redirects reach your live site when you publish. See How to publish a web app.
• A category's old addresses need category pages (Settings → Listing → Category Pages). Without them, the category's addresses aren't redirected, and the import's notes say so. See How to use blog categories, tags and related posts.

Check that it worked#

• The categories show as pills at the top of the panel, nested like your folders.
• Open an article: its pictures, links and callouts are in place.
• In Project settings → SEO & social → Search engines → Custom Redirects, the old addresses are listed.

Troubleshooting#

"Could not read the file: …" The ZIP is damaged, or isn't a ZIP. Zip the folder again and drop the new file.

"No Markdown articles found" The ZIP holds no .md files outside left-out folders (those starting with _ or .). Check where your articles are.

"… shares the address "…" with …; only the first is imported" Two files end up with the same address. Give one of them its own slug.

A note says a picture "is not in the bundle, dropped" The article refers to a picture that isn't in the ZIP at that path. Add it next to the article and import again: the article is updated in place.

The plan says pictures are .avif (or .heic, .heif, .bmp, .tif, .tiff) "which TeleportHQ cannot upload" TeleportHQ doesn't upload pictures in those formats, so the import leaves them out of the articles, and the panel stays open after the import with the same note until you click Done. Convert the pictures to .png, .jpg or .webp, change their paths in the articles to the new file names, zip the folder again and import it: the articles are updated in place.

A note says a related article "was not found, left out" No file in the ZIP and no article already in your help center has that address. Fix the address under related.

A note says Unreadable date "…", ignoring it Write dates as 2026-03-15.

My Markdown pictures didn't come in from a single .md file A single file brings no pictures by path. Zip the file with its pictures and import the ZIP. Pictures linked by web address stay as links either way.

Good to know#

• Blog and Help Center import Markdown the same way. The Blog's addresses start with /blog/, the Help Center's with /help/. Category redirects work in the Help Center from the start; in the Blog, turn on Category Pages first.
• The button reads Import N articles in both, and the message counts "articles" in the Help Center and "posts" in the Blog.
• Imports set each article's last-updated date (last_verified, updated_at), which your live sitemap and llms.txt use. See How to set SEO for a blog post.
• Front matter names TeleportHQ doesn't know are ignored. Raw HTML in the text shows as text, and HTML comments are removed.