How to import Markdown files into a Zendesk Guide knowledge base

To import Markdown into a Zendesk knowledge base, install Quirewell, open it from the left navigation bar and pick the folder (or a zip) that holds your .md files and their images. Choose Folders become sections, set the article settings, click Preview import and then Import N articles. Each file becomes an article, its images are uploaded into your help center, and links between your files point at the new articles.

What Quirewell reads

Files ending in .md, .markdown or .txt. Supported Markdown includes GitHub-style tables, fenced code with its language, strikethrough, links, pictures and raw HTML. Task lists become plain list items. The help center editor stores articles as HTML, so the Markdown is converted on import; there is no Markdown left to maintain inside Zendesk.

Steps

1. Pick the folder. Click Pick a folder and choose the root of your docs, or pick a zip of it. Include the image folders, so pictures can be uploaded.
2. Choose where they go. Pick a default Category and Section, then Folders become sections (two levels deep: category, then section). A file in Billing/Refunds/ goes to the section "Refunds" in the category "Billing". The folder every file shares is skipped.
3. Pick the Language. It is the source language of the articles.
4. Set the article settings: Visible to, Permission group (who can edit), Labels for every article, drafts (on by default), promoted, comments off.
5. Click Preview import. Check where each file goes, how many images it has, and any notes.
6. Click Import N articles.

Front matter

Optional front matter at the top of a file overrides the folders for that file.

---
title: Resetting your password
category: Account
section: Sign-in
labels: [password, login]
locale: fr
draft: true
promoted: false
---

Images

Pictures your Markdown points at with a relative path, such as ![Settings](images/settings.png), are uploaded into your help center and the article uses the new address, so nothing depends on the old docs host. PNG, JPG and GIF are used as they are; WebP, BMP, SVG and AVIF are converted to PNG. Pictures referenced only by a web address (https://...) stay where they are. If a relative path doesn't match a file you picked, the preview says "Image not found in the files you picked".

Links between files

A link from one Markdown file to another in the same import, such as [Refunds](../billing/refunds.md#partial), is rewritten to the new article once it exists. The #section part is kept.

Translations

Docs sites that keep each language in its own folder import as translations: put each language in a top folder named after it, such as en-us/Billing/refunds.md and fr/Billing/refunds.md. Or name files with the code before the extension: refunds.md, refunds.fr.md. Each set becomes one article with translations. The languages must be turned on in your help center.

Undo

History lists each import with its name, time and who ran it. Undo archives the import's articles, deletes the sections and categories it created when they hold nothing else, and deletes the pictures it uploaded. Run imports as a Zendesk admin so History survives a page reload.

What it costs

Quirewell is $99 a month per Zendesk account, with any number of imports, articles, languages and admins. It has a 14-day free trial; Zendesk asks for a card at install and bills monthly. Every option is in the Quirewell documentation.